macltok

public

Star0

Fork 0

Watch0

3 commits 3 branches 0 tags 0 releases3.0 MiB

Commit `31ce2453c82f`

tarball

atagen <boss@atagen.co>2026-09-24 23:43 UTC

32 files changed+5086-6553

engine: answer every command directly and keep the event stream for state

Correlating CommandIds against a shared stream made every client rebuild request and response, and a web backend could not serve media bytes per request at all. Each Command now carries a Responder, and dropping one answers Interrupted, so panics, closed rooms and shutdown need no bookkeeping. Media, profiles and space hierarchies became handle queries, and RoomSummary grew the fields a room list needs, so Malice needs no direct matrix-sdk. One cloneable Error replaces the four error types.

Modified file: Cargo.toml+1−1

@@ -11,7 +11,7 @@ sqlite = ["matrix-sdk/sqlite", "serde", "dep:url"]

1111 bundled-sqlite = ["sqlite", "matrix-sdk/bundled-sqlite"]

1212

1313 [dependencies]

14-futures-util = { version = "0.3.31", default-features = false }

14+futures-util = { version = "0.3.31", default-features = false, features = ["std"] }

1515 http = "1"

1616 matrix-sdk = { version = "0.18.0", default-features = false, features = ["e2e-encryption"] }

1717 matrix-sdk-crypto = { version = "0.18.0", default-features = false }

Modified file: README.md+10 additions−10 deletions@@ -21,16 +21,16 @@ already have remote event IDs.
 
 ## Consuming the engine
 
-Run `Engine::run` and drain its single `EventStream` independently of command
-submission. `ClientHandle::send` returns an enqueue ID; match that ID against
-`CommandSucceeded`, `CommandSucceededWithRoom`, or `CommandFailed` before
-reporting completion. A successful message command only enters the SDK send
-queue; the timeline item's send state reports subsequent network delivery.
-
-Start a timeline from `TimelineReset`, then apply `TimelineChanged` diffs with
-`TimelineDiff::try_apply`. If a diff does not match the current snapshot, stop
-applying diffs for that timeline and send `TimelineCommand::Resync`. Resume only
-after its fresh `TimelineReset`; the reset precedes the command completion.
+spawn `Engine::run`, drain the `EventStream` from its own task, and talk to the
+engine through `ClientHandle`. every command answers once, awaited
+(`handle.send_message(..).await?`) or as a `Pending` you can await later or
+drop. a sent message answers when the sdk send queue has it, delivery shows up
+as the timeline item's send state. reads like `rooms`, `members` and `media`
+go straight to the sdk. the stream only carries state
+
+start a timeline from `TimelineReset`, then apply `TimelineChanged` diffs with
+`TimelineDiff::try_apply`. when one doesn't fit, stop applying, call `resync`,
+and pick up from the next `TimelineReset`
 
 With `sqlite`, persist the initial `Session::record()` separately from its
 encrypted SQLite store. On `SessionTokensChanged`, obtain a new record from

Modified file: docs/design-decisions.md+137 additions−170 deletions@@ -1,172 +1,139 @@
 # macltok design decisions
 
-This document describes the contract implemented in the working tree.
-
-## Engine execution
-
-The engine keeps a contextual task registry. Every spawned task is registered
-with either its command id and kind, a watcher name, or a room id and
-generation. The run loop continuously joins completed tasks and removes their
-context. A command-task panic produces its correlated `CommandFailed` event.
-A watcher or current room-actor panic is terminal to the engine. Shutdown aborts
-and joins the remaining registered tasks.
-
-The engine emits `Authenticated`, then `ConnectionChanged(Connecting)`, before
-starting the sync service. `ConnectionChanged` also represents the later SDK
-states and the final `Stopped` transition. `Engine::run` returns an
-`EngineError` for terminal failure and emits `Failed` before `Stopped` when the
-event stream remains available.
-
-The driver command channel remains lossless and clients must drain
-`EventStream` independently of command submission. `ClientHandle` also exposes
-a `watch` receiver for the current connection state. `RoomsChanged` is an
-invalidation event. Call `ClientHandle::rooms` for current, normalised room
-summaries.
-
-`ClientHandle` sends `Command` values and receives a `CommandId`. Completion is
-reported as `CommandSucceeded`, `CommandSucceededWithRoom`, or
-`CommandFailed`. `CommandFailure` contains the id, outer `CommandKind`, typed
-`CommandErrorKind`, and display message. Direct request and response methods
-return `CommandResultError`, which is either a delivered `CommandFailure` or a
-closed reply channel.
-
-For timeline sends, success means the SDK send queue accepted the event;
-network delivery is reported later through timeline send state.
-
-`send` reports enqueueing, not completion. Consumers retain the returned id
-until a terminal result with that id arrives; they match `CommandFailure::kind`
-rather than parsing its display message. The event stream must be drained while
-commands are submitted, even when several frontend clients share one engine.
-
-## Room lifetime and ordering
-
-An open room has an explicit generation and exactly one of three states.
-
-- `Opening` owns the generation and actor request sender
-- `Open` owns the generation and actor request sender
-- `Closing` owns the generation and a bounded FIFO of deferred open and close commands
-
-An `Open` command starts an actor immediately and returns its terminal result
-only after the actor reports readiness. There is no separate readiness waiter or
-readiness task. Repeated opens while opening are retained by the actor and each
-gets one terminal result. A close changes the room to `Closing`, rejects work
-that needs an open actor, and waits for that generation to exit. Opens and
-closes during closing are queued in order; after exit, each deferred command is
-replayed, with a fresh generation started when needed. Events from earlier
-generations are ignored.
-
-Each room actor serialises its timeline work in FIFO order. Different rooms run
-concurrently. Room mutations which do not require an open timeline use a
-separate keyed FIFO scheduler. Jobs with the same room, target, or direct-chat
-key run in submission order while unrelated keys run concurrently. Notification
-commands and encryption commands each have one dedicated serial worker. The
-encryption worker owns the verification controller and cancels it before
-shutdown completes.
-
-Pagination has a per-timeline mutex gate and a session-owned completion path.
-Pagination tasks are reaped as they finish. Closing a timeline aborts its
-pagination work and emits one terminal result for every still-pending command.
-There is no public pagination handle. The internal result channel is only the
-session completion mechanism and is not an engine-wide routing design.
-
-`TimelineDiff::try_apply` rejects indices that do not match the consumer's
-snapshot without modifying that snapshot. A consumer then stops applying diffs
-for that timeline and sends `TimelineCommand::Resync`. The timeline session
-aborts and joins its old watcher, atomically subscribes to a fresh SDK snapshot
-and diff stream, and emits `TimelineReset` before the resync command succeeds.
-This works for rooms and threads without closing their timelines or pagination.
-
-Timeline diffs and resets carry `TimelineId`, which distinguishes a room from a
-thread by its root event. Thread actors and pagination state belong to the room
-actor. Stateful timeline commands require the room actor. Standalone room
-commands such as typing, receipts, send-queue control, membership actions, and
-moderation use the SDK `Room` directly.
-
-## Account construction and secrets
-
-`Session::login_password`, `Session::begin_oauth`, and `Session::restore` use
-one shared account client builder. It configures encrypted SQLite storage,
-encryption settings, refresh-token handling, and enabled threading without
-thread subscriptions. `Session::build` passes the authenticated client to the
-engine.
-
-Secret-bearing input types do not derive `Clone`. The store passphrase is
-borrowed by the shared builder, password login passes its password by reference,
-and authentication records are cloned only where SDK ownership requires it.
-
-The caller owns durable authentication records. Save `Session::record()` after
-login, then consume `SessionTokensChanged` and atomically replace that saved
-record with `ClientHandle::session_record()`. A previously captured record may
-hold an exhausted refresh token; failing to persist a rotation must be surfaced
-rather than silently treating the stale record as safe to restore. Restore with
-the same `StoreConfig` path and passphrase. logout and a rejected token both
-stop the engine. logout and a hard rejection kill the record and the store, a
-soft logout keeps the store for a same-device login, `Stopped` alone kills
-nothing. Neither cookies nor application-specific secret storage belong in the
-toolkit.
-
-## Notifications and room data
-
-The notification client is constructed lazily in an `OnceCell` and shares the
-engine sync service. It is created only when notification resolution is first
-requested. `PushNotification` exposes typed room and sender metadata and a
-typed `PushNotificationEvent`. The event is `Raw<AnySyncTimelineEvent>` for a
-timeline notification or `Raw<StrippedRoomMemberEvent>` for an invite. SDK UI
-types do not cross the public boundary.
-
-Room summaries are normalised once per `rooms` query. `ClientHandle::rooms_filtered`
-normalises its name search term once before filtering. Summary generation runs
-display-name requests with bounded concurrency. Sorting is descending latest
-event timestamp, then case-insensitive name, then room id as a deterministic tie
-break.
-
-Global and room account data retain typed Matrix event-type parameters and raw
-event content. The handle offers direct raw reads and engine-backed raw writes.
-
-## Commands and errors
-
-`Command` is grouped into `Account`, `Room`, `Timeline`, `Media`,
-`Encryption`, `Notification`, and `Lifecycle` domains. `CommandKind` identifies
-the outer domain in result events.
-
-`RoomCommand::InviteUser` contains only room and user ids. It deliberately does
-not expose a reason because the SDK invite helper accepts none. Kick, ban, and
-unban retain optional reasons where the protocol supports them.
-
-`TimelineCommand::Edit` accepts `MessageEditContent`. Its `Text` and `Emote`
-variants carry `RichText`, so edited text and emotes preserve plain text,
-optional Matrix HTML, and mentions. Empty edited bodies fail with `EmptyBody`.
-
-`VerificationAction` contains `Confirm`, `Reject`, and `Cancel`. Starting a
-verification is a target-bearing encryption command rather than an action.
-Verification progress uses `Waiting`, `Comparison`, `Confirmed`, `Done`,
-`Cancelled`, and typed `Failed(VerificationFailure)`. Request acceptance, SAS
-startup and acceptance failures retain their message, while stream termination
-has dedicated variants. A cancelled verification can be started again.
-The watcher and action paths claim terminal emission so a racing cancellation
-cannot replace `Done` with a local `Cancelled` event.
-
-`CommandErrorKind` is the stable typed failure category. It includes room and
-timeline availability, queue pressure, validation, media, verification,
-authentication, network, server, store, timeline, encryption, and fallback
-categories. The rendered message preserves operation context while internal
-errors retain their source chains.
-
-## Power levels
-
-Power-level reads return the complete local `RoomPowerLevels` mapping.
-`PowerLevelChanges` applies selected common and well-known event thresholds,
-and `SetUserPowerLevel` changes one user mapping.
-
-The SDK trait that applies a power-level event is crate-private. macltok keeps
-an atomic local mapping, applies all requested changes to it, and sends one
-state event. It does not patch upstream and does not send separate events for
-individual fields.
-
-## Public model boundaries
-
-The public model uses owned ruma identifiers and typed data wherever it has a
-stable representation. Raw Matrix event payloads remain `Raw` where arbitrary
-event content must be preserved. Public output models are non-exhaustive where
-they are expected to grow. SDK clients remain available through the handle for
-direct state queries that do not need engine coordination.
+the contract the working tree actually implements. if the code disagrees with
+this, one of them is lying and it should be fixed
+
+## two ways in, one way out
+
+state changes are commands. `ClientHandle::send` queues one and hands back a
+`Pending`, `execute` queues and waits, and there's an awaited convenience method
+for every command. each command answers exactly once with
+`Result<CommandOutput, Error>`. drop the `Pending` if you don't care, the
+command still runs
+
+pure reads skip the engine and ask the sdk directly through the handle. rooms,
+members, power levels, account data, devices, push notification resolution,
+and media bytes all live here
+
+the event stream carries state and only state. timelines, history, typing,
+rooms, connection, encryption, verification, upload progress, session. no
+command results ride on it. drain it from its own task, it's bounded and the
+engine waits for you
+
+one error type for everything, `Error { kind, message, challenge }`. match on
+`kind`. `Interrupted` means the engine stopped, the room closed, or the task
+doing the work died before it could answer. `challenge` turns up with
+`InteractiveAuthRequired`
+
+## engine
+
+the run loop routes and does nothing slow. every task it spawns is registered
+with a context. a command task that panics costs its caller an `Interrupted`
+and gets logged. a watcher or a room actor that panics takes the engine down,
+emitting `Failed` then `Stopped`
+
+sync restarts itself with backoff after an error or an unexpected stop, and
+`ConnectionChanged` shows `Offline` meanwhile. every return to `Online` re-arms
+the send queues, since the sdk parks a room's queue on any send failure and
+never unparks it. a recoverable failure while online gets the room another go
+after a few seconds
+
+logout and a rejected token both stop the engine. `Shutdown` answers once
+`Stopped` has gone out
+
+## rooms
+
+one actor per open room. the engine holds a slot per room, `Active` with a
+sender or `Closing` with a fifo of opens and closes that arrived while it wound
+down. those replay in order once the actor exits. a room you leave, or get
+kicked or banned from, closes itself
+
+opening sends `TimelineReset` on the stream before it answers. opening an
+already open room sends a fresh reset, so a second frontend gets a snapshot
+
+sends, edits and replies run on the actor in order, so they reach the send
+queue in the order they were asked for. redactions, reactions and read
+receipts are network calls, so they run beside the actor and a slow one
+doesn't queue the room behind it. closing lets them finish rather than lie
+
+threads belong to their room's actor. commands for a thread that's still
+opening wait behind the open, up to the actor's queue capacity
+
+pagination runs one request at a time per timeline and emits `HistoryChanged`
+around each. the sdk remembers where history starts, we don't, because a gappy
+sync can unload it again
+
+every task inside an actor is supervised, and a panic in any of them panics the
+actor
+
+## timelines
+
+`TimelineDiff::try_apply` refuses a diff whose indices don't fit your snapshot
+and leaves the snapshot alone. stop applying, `resync`, and carry on from the
+next `TimelineReset`. resync kills the old watcher before the new reset goes
+out, so no stale diff can land after it
+
+`TimelineId` tells a room from a thread by its root event
+
+## mutations
+
+membership, moderation, power levels, room creation and account data writes go
+through one keyed fifo scheduler. same room, same alias, same dm partner or
+same account data type run in order, everything else runs at once.
+`create_direct` hands back the existing dm when there is one
+
+notifications and encryption each get one serial worker. the encryption worker
+owns the verification controller outright
+
+power level changes build one state event from the local mapping, since the
+sdk's own patcher is private
+
+## media
+
+media is a read. `ClientHandle::media` takes a `MediaId` a retained timeline
+handed you, `mxc_media` takes any plain mxc uri. both share one bounded
+download path with the byte cap the sdk's own download lacks, and
+concurrent asks for the same bytes share one flight
+
+the cache holds plaintext, keyed like the sdk keys it, so the sdk and macltok
+can read each other's entries. that's how your own encrypted uploads come back
+
+media ids are registered as timelines render and forgotten when their timeline
+closes, least recently seen first once the cap is hit
+
+uploads are commands that answer once the send queue has them. progress and
+failure arrive as events from one watcher on the sdk's global send queue
+
+## sessions and secrets
+
+`Session::login_password`, `begin_oauth` and `restore` share one client builder
+with encrypted sqlite, refresh tokens and threads. secret-bearing inputs don't
+derive `Clone`
+
+the caller owns the saved record. save `Session::record()` after login and
+replace it atomically with `ClientHandle::session_record()` on every
+`SessionTokensChanged`. logout and a hard rejection kill the record and the
+store. a soft logout keeps the store for a same-device login, or the e2ee keys
+go with it. a bare `Stopped` kills nothing. one store directory per login
+
+## notifications and room data
+
+the notification client is built lazily and shares the engine's sync service.
+sdk ui types stay behind the boundary
+
+`rooms` normalises on demand with bounded concurrency and sorts by latest event,
+then name, then id. `RoomsChanged` is an invalidation, coalesced so one sync
+touching fifty rooms is one event
+
+## verification
+
+`Confirm`, `Reject` and `Cancel`. reject tells the other side the emoji didn't
+match. the watcher and the action paths claim the terminal event, so a racing
+cancel can't turn `Done` into `Cancelled`
+
+## public model
+
+owned ruma ids and typed data wherever there's a stable shape, `Raw` where
+arbitrary content has to survive. anything expected to grow is
+`#[non_exhaustive]`. `Engine::from_client` stays public for people who built
+their own client

Modified file: docs/review-2026-09-24.md+13 additions−11 deletions@@ -68,7 +68,7 @@ ciphertext as if it were the image. The media tests force plaintext rooms
 Fix direction. Cache plaintext, matching the SDK, and keep the byte bound by
 decrypting in a streaming fashion before the write.
 
-### C5. Media single-flight is poisoned by a leader panic. folded into the media query rewrite under q1
+### C5. Media single-flight is poisoned by a leader panic. done, shared-future single flight in the media query
 
 In `spawn_media_fetch` (`src/engine.rs:1870-1911`) followers push their id and
 return at once, trusting the leader to answer for them. If `fetch_media`
@@ -132,7 +132,7 @@ Fix direction. When the room is open, route through the actor and use
 already talk to creates a duplicate every time. `Client::get_dm_room` exists
 for the lookup (`client/mod.rs:1852`).
 
-### C11. Unregistered tasks swallow panics, contradicting the design doc. folded into q1 and the actor restructure
+### C11. Unregistered tasks swallow panics, contradicting the design doc. done, command tasks answer `Interrupted`, actor internals are supervised and panic the actor
 
 The design doc says a watcher panic is terminal. But the timeline watcher
 (`src/engine.rs:589`), pagination worker (`446`), pagination result task
@@ -161,7 +161,7 @@ loaded in a room that is still open are the first evicted, and fetching them
 then fails with `MediaUnknown`. Closed timelines never release their entries,
 so they compete with open ones.
 
-### C14. Smaller correctness issues. mostly done. `open_room` on an open room waits for q1 snapshots, the lagged watcher stays as is
+### C14. Smaller correctness issues. done, bar the lagged session watcher which stays as is
 
 - `CommandResultError::Failed` renders its `Display` through `Debug`
   (`src/transport.rs:840`), so users see a struct dump.
@@ -185,7 +185,7 @@ so they compete with open ones.
 
 ## A. API shape and client-builder friendliness
 
-### A1. Three completion mechanisms, and the useful one is rationed. OPEN
+### A1. Three completion mechanisms, and the useful one is rationed. done, one awaited path and one error type
 
 A client must know which of three patterns each operation uses.
 
@@ -202,7 +202,7 @@ The headless example is mostly bookkeeping of ids. Malice gap 4 comes straight
 from this. The one pattern a web backend can use, an awaited result per
 request, is not offered for most operations.
 
-### A2. Pure reads modelled as commands, against the doc's own rule. OPEN
+### A2. Pure reads modelled as commands, against the doc's own rule. done, `media` and `mxc_media` are handle queries
 
 The design doc says operations are split by whether they change state. Media
 fetch changes no state, yet it is a `MediaCommand` whose bytes arrive as a
@@ -210,7 +210,7 @@ fetch changes no state, yet it is a `MediaCommand` whose bytes arrive as a
 other frontend's image bytes, up to 20 MiB each, and the requester has to
 filter by `MediaId`.
 
-### A3. Every timeline item is a `Message`, with presentation strings in `body`. OPEN
+### A3. Every timeline item is a `Message`, with presentation strings in `body`. open, q3
 
 `normalise_timeline_item` (`src/normalise/timeline.rs`) flattens every event
 into `TimelineMessage`. The consequences for a client are these.
@@ -235,7 +235,7 @@ This needs a content enum, for example `Message { msgtype, ... }`, `Redacted`,
 `UnableToDecrypt`, `Membership`, `ProfileChange`, `RoomState`, `Poll` and
 `Other { event_type }`. It is the largest single rendering gap.
 
-### A4. Timeline commands cannot target local echoes. OPEN
+### A4. Timeline commands cannot target local echoes. open, lands with q3
 
 `Edit`, `Redact` and `ToggleReaction` take an `OwnedEventId` and wrap it in
 `TimelineEventItemId::EventId`. The SDK accepts transaction ids for all three,
@@ -243,13 +243,13 @@ but a client cannot edit, redact or react to a message it sent until the
 server echo arrives. The commands should take the identifier that the model
 already exposes.
 
-### A5. `RoomSummary` is too thin for a room list. OPEN
+### A5. `RoomSummary` is too thin for a room list. open, lands with the malice queries and q2
 
 Missing fields, all cheap SDK reads. Topic, canonical alias, joined and invited
 member counts, heroes, tombstone and successor, inviter for invites, a latest
 event preview, and space parents and children (Malice gap 3).
 
-### A6. No incoming verification. OPEN
+### A6. No incoming verification. open
 
 Only outgoing `StartVerification` exists. A request started from another
 device, which is the normal "verify this new login" flow, is never observed.
@@ -257,7 +257,7 @@ macltok registers no handler for it, and the SDK has no stream, so the app
 pattern is an event handler plus `Encryption::get_verification_request`
 (`encryption/mod.rs:1060`).
 
-### A7. Missing `#[non_exhaustive]`. OPEN
+### A7. Missing `#[non_exhaustive]`. done
 
 Adding the attribute later is itself a breaking change, so it belongs now. Output types that will
 grow are `TimelineItem`, `CommandKind`, `RoomMembership`, `VerificationState`,
@@ -265,7 +265,7 @@ grow are `TimelineItem`, `CommandKind`, `RoomMembership`, `VerificationState`,
 grow need a constructor plus `#[non_exhaustive]`. These are
 `CreateRoomOptions`, `PasswordLogin`, `OAuthLogin` and `UploadThumbnail`.
 
-### A8. Smaller API issues. OPEN
+### A8. Smaller API issues. mostly done. `HistoryState::Failed(String)`, stringly power level events and fixed encryption defaults remain
 
 - `MediaCommand::Upload` duplicates `UploadAttachment`, and the handle exposes
   both `upload_media` and `upload_attachment`.
@@ -284,6 +284,8 @@ grow need a constructor plus `#[non_exhaustive]`. These are
 
 ## D. Duplication and antipatterns
 
+mostly done by the engine split. the actor thread registry, one spawn helper, one responder, one media request path, one test support module. `get_room` lookups went from twenty one hand rolled errors to a helper per module
+
 Line references are from the mechanical inventory taken during this review.
 
 - `RoomActor::run` is about 700 lines. The "queue while the thread is opening,

Modified file: examples/headless.rs+54 additions−54 deletions@@ -1,76 +1,69 @@
 use macltok::{
-    Command, CommandKind, EngineConfig, Event, LifecycleCommand, PasswordLogin, RoomCommand,
-    RoomMembership, Session, StoreConfig, TimelineCommand,
+    EngineConfig, Event, PasswordLogin, RoomMembership, Session, StoreConfig, TimelineId,
+    TimelineItem,
 };
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let homeserver = required("MATRIX_HOMESERVER")?;
-    let username = required("MATRIX_USERNAME")?;
-    let password = required("MATRIX_PASSWORD")?;
-    let store_path = required("MATRIX_STORE_PATH")?;
-    let store_passphrase = required("MATRIX_STORE_PASSPHRASE")?;
     let session = Session::login_password(
-        PasswordLogin {
-            homeserver,
-            username,
-            password,
-            device_display_name: Some("macltok headless example".into()),
-            device_id: None,
-        },
-        StoreConfig::new(store_path, store_passphrase),
+        PasswordLogin::new(
+            required("MATRIX_HOMESERVER")?,
+            required("MATRIX_USERNAME")?,
+            required("MATRIX_PASSWORD")?,
+        )
+        .with_device_display_name("macltok headless example"),
+        StoreConfig::new(
+            required("MATRIX_STORE_PATH")?,
+            required("MATRIX_STORE_PASSPHRASE")?,
+        ),
     )
     .await?;
     let (engine, handle, mut events) = session.build(EngineConfig::default()).await?;
     let running = tokio::spawn(engine.run());
-    let mut room_open_id = None;
-    let mut resync_id = None;
-    let mut timeline_items = Vec::new();
+    let mut opened: Option<TimelineId> = None;
+    let mut items = Vec::new();
+    let mut stale = false;
 
     loop {
         tokio::select! {
             event = events.recv() => {
-                let Some(event) = event else { break; };
+                let Some(event) = event else { break };
                 match event {
-                    Event::RoomsChanged if room_open_id.is_none() => {
-                        if let Some(room) = handle
+                    Event::RoomsChanged if opened.is_none() => {
+                        let Some(room) = handle
                             .rooms()
                             .await
                             .into_iter()
                             .find(|room| room.membership == RoomMembership::Joined)
-                        {
-                            room_open_id = Some(handle
-                                .send(Command::Room(RoomCommand::Open(room.room_id)))
-                                .await?);
-                        }
+                        else {
+                            continue;
+                        };
+                        opened = Some(room.room_id.clone().into());
+                        // answers arrive on their own, the event loop keeps draining meanwhile
+                        let handle = handle.clone();
+                        tokio::spawn(async move {
+                            if let Err(error) = handle.open_room(room.room_id).await {
+                                eprintln!("could not open {error}");
+                            }
+                        });
                     }
-                    Event::TimelineReset { items, .. } => {
-                        timeline_items = items;
-                        resync_id = None;
+                    Event::TimelineReset { timeline_id, items: snapshot }
+                        if opened.as_ref() == Some(&timeline_id) =>
+                    {
+                        items = snapshot;
+                        stale = false;
+                        print_messages(&items);
                     }
-                    Event::TimelineChanged { timeline_id, diffs } if resync_id.is_none() => {
-                        for diff in diffs {
-                            if diff.try_apply(&mut timeline_items).is_err() {
-                                resync_id = Some(handle.send(Command::Timeline(
-                                    TimelineCommand::Resync { timeline_id },
-                                )).await?);
-                                break;
-                            }
-                        }
-                        if resync_id.is_none() {
-                            for item in &timeline_items {
-                                if let macltok::TimelineItem::Message(message) = item {
-                                    println!("{}  {}", message.sender_name, message.body);
-                                }
-                            }
+                    Event::TimelineChanged { timeline_id, diffs }
+                        if !stale && opened.as_ref() == Some(&timeline_id) =>
+                    {
+                        if diffs.into_iter().any(|diff| diff.try_apply(&mut items).is_err()) {
+                            stale = true;
+                            let handle = handle.clone();
+                            tokio::spawn(async move { handle.resync(timeline_id).await });
+                            continue;
                         }
-                    }
-                    Event::CommandSucceeded { id, command: CommandKind::Room }
-                        if room_open_id == Some(id) => println!("room ready"),
-                    Event::CommandFailed(error) if room_open_id == Some(error.id)
-                        || resync_id == Some(error.id) => return Err(error.message.into()),
-                    Event::CommandFailed(error) => {
-                        eprintln!("{:?}  {}", error.command, error.message);
+                        print_messages(&items);
                     }
                     Event::Stopped => break,
                     _ => {}
@@ -78,9 +71,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             }
             result = tokio::signal::ctrl_c() => {
                 result?;
-                handle
-                    .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-                    .await?;
+                let handle = handle.clone();
+                tokio::spawn(async move { handle.shutdown().await });
             }
         }
     }
@@ -88,6 +80,14 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
+fn print_messages(items: &[TimelineItem]) {
+    for item in items {
+        if let TimelineItem::Message(message) = item {
+            println!("{}  {}", message.sender_name, message.body);
+        }
+    }
+}
+
 fn required(name: &str) -> Result<String, Box<dyn std::error::Error>> {
     std::env::var(name).map_err(|_| format!("{name} is required").into())
 }

Modified file: src/account.rs+71 additions@@ -27,6 +27,7 @@ pub struct Session {
     record: SessionRecord,
 }
 
+#[non_exhaustive]
 pub struct PasswordLogin {
     pub homeserver: String,
     pub username: String,
@@ -36,6 +37,36 @@ pub struct PasswordLogin {
     pub device_id: Option<OwnedDeviceId>,
 }
 
+impl PasswordLogin {
+    #[must_use]
+    pub fn new(
+        homeserver: impl Into<String>,
+        username: impl Into<String>,
+        password: impl Into<String>,
+    ) -> Self {
+        Self {
+            homeserver: homeserver.into(),
+            username: username.into(),
+            password: password.into(),
+            device_display_name: None,
+            device_id: None,
+        }
+    }
+
+    #[must_use]
+    pub fn with_device_display_name(mut self, name: impl Into<String>) -> Self {
+        self.device_display_name = Some(name.into());
+        self
+    }
+
+    #[must_use]
+    pub fn with_device_id(mut self, device_id: OwnedDeviceId) -> Self {
+        self.device_id = Some(device_id);
+        self
+    }
+}
+
+#[non_exhaustive]
 pub struct OAuthLogin {
     pub homeserver: String,
     pub redirect_uri: String,
@@ -46,7 +77,47 @@ pub struct OAuthLogin {
     pub application_type: OAuthApplicationType,
 }
 
+impl OAuthLogin {
+    #[must_use]
+    pub fn new(
+        homeserver: impl Into<String>,
+        redirect_uri: impl Into<String>,
+        client_uri: impl Into<String>,
+        application_type: OAuthApplicationType,
+    ) -> Self {
+        Self {
+            homeserver: homeserver.into(),
+            redirect_uri: redirect_uri.into(),
+            client_uri: client_uri.into(),
+            client_name: None,
+            client_id: None,
+            device_id: None,
+            application_type,
+        }
+    }
+
+    #[must_use]
+    pub fn with_client_name(mut self, name: impl Into<String>) -> Self {
+        self.client_name = Some(name.into());
+        self
+    }
+
+    /// a statically registered client id, skipping dynamic registration
+    #[must_use]
+    pub fn with_client_id(mut self, client_id: impl Into<String>) -> Self {
+        self.client_id = Some(client_id.into());
+        self
+    }
+
+    #[must_use]
+    pub fn with_device_id(mut self, device_id: OwnedDeviceId) -> Self {
+        self.device_id = Some(device_id);
+        self
+    }
+}
+
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
 pub enum OAuthApplicationType {
     Native,
     Web,

Modified file: src/encryption.rs+88 additions−115 deletions@@ -17,9 +17,9 @@ use ruma::{OwnedDeviceId, UserId};
 use tokio::{sync::Mutex, task::JoinHandle};
 
 use crate::{
-    CommandErrorKind, EncryptionState, Event, KeyBackupState, RecoveryState, VerificationAction,
-    VerificationState as UiState, VerificationTarget, error::CommandError,
-    model::VerificationFailure, transport::EventSender,
+    EncryptionState, Error, ErrorKind, Event, KeyBackupState, RecoveryState, VerificationAction,
+    VerificationState as UiState, VerificationTarget, model::VerificationFailure,
+    transport::EventSender,
 };
 
 pub(crate) fn encryption_state(
@@ -64,10 +64,9 @@ struct VerificationSession {
 impl VerificationController {
     pub(crate) async fn apply(
         &mut self,
-        _client: &Client,
         sender: EventSender,
         action: VerificationAction,
-    ) -> Result<(), CommandError> {
+    ) -> Result<(), Error> {
         match action {
             VerificationAction::Confirm => {
                 // Retain a handle across the operation: the watcher clears
@@ -76,9 +75,7 @@ impl VerificationController {
                 let sas = self.active.lock().await.sas.clone();
                 match self.confirm().await {
                     Ok(()) => Ok(()),
-                    Err(error) if error.kind == CommandErrorKind::VerificationInactive => {
-                        Err(error)
-                    }
+                    Err(error) if error.kind == ErrorKind::VerificationInactive => Err(error),
                     // The confirm advanced local SDK state before its send failed,
                     // so the retained session could report success on retry without
                     // network traffic. Best-effort cancel (no lock held across the
@@ -153,8 +150,8 @@ impl VerificationController {
                                             )))
                                             .await;
                                     }
-                                    return Err(CommandError::new(
-                                        CommandErrorKind::VerificationInactive,
+                                    return Err(Error::new(
+                                        ErrorKind::VerificationInactive,
                                         info.reason().to_owned(),
                                     ));
                                 }
@@ -185,8 +182,8 @@ impl VerificationController {
                         )))
                         .await
                         .map_err(|source| {
-                            CommandError::with_source(
-                                CommandErrorKind::EventReceiverClosed,
+                            Error::with_source(
+                                ErrorKind::Interrupted,
                                 "event receiver has closed",
                                 source,
                             )
@@ -202,14 +199,14 @@ impl VerificationController {
         client: &Client,
         sender: EventSender,
         target: VerificationTarget,
-    ) -> Result<(), CommandError> {
+    ) -> Result<(), Error> {
         client
             .encryption()
             .wait_for_e2ee_initialization_tasks()
             .await;
         let own_user_id = client.user_id().ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::Unauthenticated,
+            Error::new(
+                ErrorKind::Unauthenticated,
                 "the Matrix client is not authenticated",
             )
         })?;
@@ -231,15 +228,15 @@ impl VerificationController {
                     .get_device(user_id, device_id)
                     .await
                     .map_err(|source| {
-                        CommandError::with_source(
-                            CommandErrorKind::Encryption,
+                        Error::with_source(
+                            ErrorKind::Encryption,
                             "reading the verification device failed",
                             source,
                         )
                     })?
                     .ok_or_else(|| {
-                        CommandError::new(
-                            CommandErrorKind::VerificationUnsupported,
+                        Error::new(
+                            ErrorKind::VerificationUnsupported,
                             "the verification device is unavailable",
                         )
                     })?;
@@ -247,7 +244,7 @@ impl VerificationController {
                     .request_verification_with_methods(vec![VerificationMethod::SasV1])
                     .await
                     .map_err(|source| {
-                        CommandError::from_sdk("starting device verification failed", source)
+                        Error::from_sdk("starting device verification failed", source)
                     })?
             }
         };
@@ -256,21 +253,13 @@ impl VerificationController {
             .send(Event::VerificationTargetChanged(target))
             .await
             .map_err(|source| {
-                CommandError::with_source(
-                    CommandErrorKind::EventReceiverClosed,
-                    "event receiver has closed",
-                    source,
-                )
+                Error::with_source(ErrorKind::Interrupted, "event receiver has closed", source)
             })?;
         sender
             .send(Event::VerificationChanged(UiState::Waiting))
             .await
             .map_err(|source| {
-                CommandError::with_source(
-                    CommandErrorKind::EventReceiverClosed,
-                    "event receiver has closed",
-                    source,
-                )
+                Error::with_source(ErrorKind::Interrupted, "event receiver has closed", source)
             })?;
         let active = self.active.clone();
         self.task = Some(tokio::spawn(async move {
@@ -279,24 +268,24 @@ impl VerificationController {
         Ok(())
     }
 
-    async fn confirm(&self) -> Result<(), CommandError> {
+    async fn confirm(&self) -> Result<(), Error> {
         let sas = self.active.lock().await.sas.clone().ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            Error::new(
+                ErrorKind::VerificationInactive,
                 "verification has not reached comparison",
             )
         })?;
         // Report a settled flow truthfully instead of as "not reached
         // comparison": the SDK would no-op the confirm with success.
         if sas.is_done() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "verification is already complete",
             ));
         }
         if let Some(info) = sas.cancel_info() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 info.reason().to_owned(),
             ));
         }
@@ -304,8 +293,8 @@ impl VerificationController {
         // remote-MAC-arrived state through the same presentable flag, while an
         // early confirm would locally no-op and falsely report success.
         if !sas.can_be_presented() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "verification has not reached comparison",
             ));
         }
@@ -315,11 +304,11 @@ impl VerificationController {
         let was_done = sas.is_done();
         sas.confirm()
             .await
-            .map_err(|source| CommandError::from_sdk("confirming verification failed", source))?;
+            .map_err(|source| Error::from_sdk("confirming verification failed", source))?;
         if sas.is_done() {
             if was_done {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     "verification is already complete",
                 ));
             }
@@ -328,52 +317,49 @@ impl VerificationController {
                 .cancel_info()
                 .map(|info| info.reason().to_owned())
                 .unwrap_or_else(|| "verification was cancelled".to_owned());
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
-                reason,
-            ));
+            return Err(Error::new(ErrorKind::VerificationInactive, reason));
         }
         Ok(())
     }
 
-    async fn reject(&self) -> Result<(), CommandError> {
+    async fn reject(&self) -> Result<(), Error> {
         let sas = self.active.lock().await.sas.clone().ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            Error::new(
+                ErrorKind::VerificationInactive,
                 "verification has not reached comparison",
             )
         })?;
         // Report a settled flow truthfully instead of as "not reached
         // comparison": the SDK would no-op the mismatch with success.
         if sas.is_done() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "verification is already complete",
             ));
         }
         if let Some(info) = sas.cancel_info() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 info.reason().to_owned(),
             ));
         }
         // Rejecting before the comparison stage would cancel a flow the user
         // never compared, so it requires the same presentable state.
         if !sas.can_be_presented() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "verification has not reached comparison",
             ));
         }
         sas.mismatch()
             .await
-            .map_err(|source| CommandError::from_sdk("rejecting verification failed", source))?;
+            .map_err(|source| Error::from_sdk("rejecting verification failed", source))?;
         // A peer completing the flow concurrently must not be reported as
         // rejected. A remote cancellation racing the send turns the SDK call
         // into a no-op success, so report it instead of a false success.
         if sas.is_done() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "verification is already complete",
             ));
         }
@@ -382,29 +368,29 @@ impl VerificationController {
             // expected reject path and stays Ok. Only a peer cancel reports an
             // error.
             if !info.cancelled_by_us() {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     info.reason().to_owned(),
                 ));
             }
         }
         Ok(())
     }
-    pub(crate) async fn cancel(&mut self) -> Result<(), CommandError> {
+    pub(crate) async fn cancel(&mut self) -> Result<(), Error> {
         self.cancel_claimed(None).await.map(|_| ())
     }
 
     /// Return whether this action won the claim for a local cancellation.
     /// The optional sender reports a peer terminal outcome when it races after
     /// the claim; starting a replacement verification does not publish it.
-    async fn cancel_claimed(&mut self, sender: Option<&EventSender>) -> Result<bool, CommandError> {
+    async fn cancel_claimed(&mut self, sender: Option<&EventSender>) -> Result<bool, Error> {
         let (sas, request) = {
             let active = self.active.lock().await;
             (active.sas.clone(), active.request.clone())
         };
         if sas.is_none() && request.is_none() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "no verification is active",
             ));
         }
@@ -415,27 +401,27 @@ impl VerificationController {
         // SDK no-op success regress Done to "cancelled by this client".
         if let Some(sas) = sas.as_ref() {
             if sas.is_done() {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     "verification is already complete",
                 ));
             }
             if let Some(info) = sas.cancel_info() {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     info.reason().to_owned(),
                 ));
             }
         } else if let Some(request) = request.as_ref() {
             if request.is_done() {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     "verification is already complete",
                 ));
             }
             if let Some(info) = request.cancel_info() {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     info.reason().to_owned(),
                 ));
             }
@@ -451,33 +437,33 @@ impl VerificationController {
             // flow and must not be disturbed.
             if let Some(sas) = sas.as_ref() {
                 if sas.is_done() {
-                    return Err(CommandError::new(
-                        CommandErrorKind::VerificationInactive,
+                    return Err(Error::new(
+                        ErrorKind::VerificationInactive,
                         "verification is already complete",
                     ));
                 }
                 if let Some(info) = sas.cancel_info() {
-                    return Err(CommandError::new(
-                        CommandErrorKind::VerificationInactive,
+                    return Err(Error::new(
+                        ErrorKind::VerificationInactive,
                         info.reason().to_owned(),
                     ));
                 }
             } else if let Some(request) = request.as_ref() {
                 if request.is_done() {
-                    return Err(CommandError::new(
-                        CommandErrorKind::VerificationInactive,
+                    return Err(Error::new(
+                        ErrorKind::VerificationInactive,
                         "verification is already complete",
                     ));
                 }
                 if let Some(info) = request.cancel_info() {
-                    return Err(CommandError::new(
-                        CommandErrorKind::VerificationInactive,
+                    return Err(Error::new(
+                        ErrorKind::VerificationInactive,
                         info.reason().to_owned(),
                     ));
                 }
             }
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "no verification is active",
             ));
         }
@@ -486,8 +472,8 @@ impl VerificationController {
             let result = sas.cancel().await;
             if sas.is_done() {
                 report_claimed_terminal(sender, UiState::Done).await;
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     "verification is already complete",
                 ));
             }
@@ -496,13 +482,10 @@ impl VerificationController {
             {
                 let reason = info.reason().to_owned();
                 report_claimed_terminal(sender, UiState::Cancelled(reason.clone())).await;
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
-                    reason,
-                ));
+                return Err(Error::new(ErrorKind::VerificationInactive, reason));
             }
             if let Err(source) = result {
-                let error = CommandError::from_sdk("cancelling verification failed", source);
+                let error = Error::from_sdk("cancelling verification failed", source);
                 report_claimed_terminal(sender, UiState::Cancelled(error.to_string())).await;
                 return Err(error);
             }
@@ -511,8 +494,8 @@ impl VerificationController {
             let result = request.cancel().await;
             if request.is_done() {
                 report_claimed_terminal(sender, UiState::Done).await;
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     "verification is already complete",
                 ));
             }
@@ -521,13 +504,10 @@ impl VerificationController {
             {
                 let reason = info.reason().to_owned();
                 report_claimed_terminal(sender, UiState::Cancelled(reason.clone())).await;
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
-                    reason,
-                ));
+                return Err(Error::new(ErrorKind::VerificationInactive, reason));
             }
             if let Err(source) = result {
-                let error = CommandError::from_sdk("cancelling verification failed", source);
+                let error = Error::from_sdk("cancelling verification failed", source);
                 report_claimed_terminal(sender, UiState::Cancelled(error.to_string())).await;
                 return Err(error);
             }
@@ -548,37 +528,36 @@ impl VerificationController {
             let _ = task.await;
         }
     }
+}
 
-    pub(crate) async fn stop(&mut self) {
-        // Shutdown path: terminate the watcher without touching the SDK so a
-        // shutdown under lock cannot hang on network sends. No terminal event
-        // is emitted; the session is simply forgotten locally.
-        self.stop_task().await;
-        clear_verification(&self.active).await;
+/// shutdown forgets the flow without telling the sdk, a network send could hang it
+impl Drop for VerificationController {
+    fn drop(&mut self) {
+        if let Some(task) = self.task.take() {
+            task.abort();
+        }
     }
 }
 
 async fn request_identity_verification(
     client: &Client,
     user_id: &UserId,
-) -> Result<VerificationRequest, CommandError> {
+) -> Result<VerificationRequest, Error> {
     let identity = client
         .encryption()
         .request_user_identity(user_id)
         .await
-        .map_err(|source| CommandError::from_sdk("requesting the user identity failed", source))?
+        .map_err(|source| Error::from_sdk("requesting the user identity failed", source))?
         .ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::NoCrossSigningIdentity,
+            Error::new(
+                ErrorKind::NoCrossSigningIdentity,
                 "the user has no cross-signing identity",
             )
         })?;
     identity
         .request_verification_with_methods(vec![VerificationMethod::SasV1])
         .await
-        .map_err(|source| {
-            CommandError::from_verification_request("starting verification failed", source)
-        })
+        .map_err(|source| Error::from_verification_request("starting verification failed", source))
 }
 
 async fn follow_request(
@@ -787,12 +766,6 @@ async fn report_claimed_terminal(sender: Option<&EventSender>, state: UiState) {
     }
 }
 
-async fn clear_verification(active: &Arc<Mutex<VerificationSession>>) {
-    let mut active = active.lock().await;
-    active.sas.take();
-    active.request.take();
-}
-
 /// Claim the active session for terminal emission, if one is still present.
 ///
 /// Exactly one party (watcher or action path) wins the claim and may emit the

Deleted file: src/engine.rs−4364 deletions@@ -1,4364 +0,0 @@
-use std::{
-    borrow::Cow,
-    collections::{HashMap, HashSet, VecDeque},
-    future::Future,
-    io::Read as _,
-    panic::AssertUnwindSafe,
-    sync::Arc,
-    time::Duration,
-};
-
-use futures_util::{FutureExt, StreamExt};
-use matrix_sdk::{
-    Client, Room, SessionChange,
-    media::{MediaFormat, MediaRequestParameters, MediaThumbnailSettings},
-    room::edit::EditedContent,
-    room::reply::{EnforceThread, Reply as SdkReply},
-    ruma::{
-        OwnedDeviceId, OwnedEventId, OwnedRoomId, RoomId,
-        api::client::receipt::create_receipt::v3::ReceiptType,
-        events::{
-            AnyGlobalAccountDataEventContent, AnyMessageLikeEventContent,
-            GlobalAccountDataEventType, Mentions, RoomAccountDataEventType,
-            receipt::ReceiptThread,
-            room::message::{
-                AddMentions, MessageType, Relation, ReplyWithinThread,
-                RoomMessageEventContentWithoutRelation,
-            },
-        },
-        serde::Raw,
-    },
-    send_queue::{LocalEchoContent, RoomSendQueueUpdate, SendHandle},
-};
-use matrix_sdk_ui::{
-    sync_service::{State as SyncState, SyncService},
-    timeline::{
-        RoomExt, Timeline, TimelineEventItemId, TimelineFocus, TimelineReadReceiptTracking,
-    },
-};
-use thiserror::Error;
-use tokio::{
-    sync::{Mutex, mpsc, oneshot, watch},
-    task::{AbortHandle, Id as TaskId, JoinHandle, JoinSet},
-};
-
-use crate::{
-    AccountCommand, AttachmentUpload, ClientHandle, Command, CommandErrorKind, CommandFailure,
-    CommandId, CommandKind, ConnectionState, CreateRoomOptions, EncryptionCommand, EngineErrorKind,
-    EngineFailure, Event, EventStream, HistoryState, InteractiveAuth, InteractiveAuthChallenge,
-    InteractiveAuthOutcome, LifecycleCommand, MediaCommand, MediaId, MediaSize, MessageContent,
-    MessageEditContent, MessageMentions, NotificationCommand, PowerLevelChanges, RichText,
-    RoomCommand, RoomNotificationMode, RoomPreset, RoomVisibility, TimelineCommand, TimelineId,
-    TypingState,
-    encryption::{VerificationController, encryption_state},
-    error::{CommandError, classify_sdk_error},
-    normalise::{MediaRegistration, MediaScope, normalise_timeline, normalise_timeline_diffs},
-    transport::{
-        ClientQueryError, CommandEnvelope, CommandResultError, DriverPort, DriverRequest,
-        EventSender, SendEventError, transport_pair,
-    },
-    upload::prepare_upload,
-};
-use matrix_sdk::ruma::api::{Metadata, OutgoingRequest, auth_scheme::SendAccessToken};
-use matrix_sdk_crypto::{AttachmentDecryptor, MediaEncryptionInfo};
-
-#[derive(Clone, Debug, Eq, PartialEq)]
-#[non_exhaustive]
-pub struct EngineConfig {
-    pub command_capacity: usize,
-    pub event_capacity: usize,
-    pub initial_history_limit: u16,
-    pub max_media_bytes: usize,
-    pub max_media_sources: usize,
-}
-
-impl EngineConfig {
-    #[must_use]
-    pub const fn with_command_capacity(mut self, capacity: usize) -> Self {
-        self.command_capacity = capacity;
-        self
-    }
-
-    #[must_use]
-    pub const fn with_event_capacity(mut self, capacity: usize) -> Self {
-        self.event_capacity = capacity;
-        self
-    }
-
-    #[must_use]
-    pub const fn with_initial_history_limit(mut self, limit: u16) -> Self {
-        self.initial_history_limit = limit;
-        self
-    }
-
-    #[must_use]
-    pub const fn with_max_media_bytes(mut self, bytes: usize) -> Self {
-        self.max_media_bytes = bytes;
-        self
-    }
-
-    #[must_use]
-    pub const fn with_max_media_sources(mut self, sources: usize) -> Self {
-        self.max_media_sources = sources;
-        self
-    }
-}
-
-impl Default for EngineConfig {
-    fn default() -> Self {
-        Self {
-            command_capacity: 64,
-            event_capacity: 128,
-            initial_history_limit: 30,
-            max_media_bytes: 20 * 1024 * 1024,
-            max_media_sources: 2_048,
-        }
-    }
-}
-
-#[derive(Debug, Error)]
-pub enum EngineError {
-    #[error("the Matrix client is not authenticated")]
-    Unauthenticated,
-    #[error("command, event, and media source capacities must be nonzero")]
-    ZeroCapacity,
-    #[error("could not build the sync service")]
-    SyncService(#[source] matrix_sdk_ui::sync_service::Error),
-    #[error("the event receiver has closed")]
-    EventReceiverClosed,
-    #[error("engine task {task} panicked")]
-    TaskPanicked { task: String },
-}
-
-impl EngineError {
-    fn failure(&self) -> EngineFailure {
-        EngineFailure {
-            kind: match self {
-                Self::EventReceiverClosed => EngineErrorKind::EventReceiverClosed,
-                Self::Unauthenticated
-                | Self::ZeroCapacity
-                | Self::SyncService(_)
-                | Self::TaskPanicked { .. } => EngineErrorKind::Other,
-            },
-            message: self.to_string(),
-        }
-    }
-}
-
-type UploadWatchers = HashMap<
-    OwnedRoomId,
-    (
-        AbortHandle,
-        watch::Receiver<Option<Result<(), CommandErrorKind>>>,
-    ),
->;
-const SYNC_RESTART_MIN: Duration = Duration::from_secs(1);
-const SYNC_RESTART_MAX: Duration = Duration::from_secs(60);
-const SEND_QUEUE_RETRY: Duration = Duration::from_secs(5);
-
-type MediaFlights = Arc<Mutex<HashMap<(MediaId, MediaSize), Vec<CommandId>>>>;
-
-pub struct Engine {
-    client: Client,
-    sync: Arc<SyncService>,
-    port: DriverPort,
-    rooms: HashMap<OwnedRoomId, RoomActorState>,
-    next_room_generation: u64,
-    room_actor_events: mpsc::UnboundedReceiver<RoomActorEvent>,
-    room_actor_event_sender: mpsc::UnboundedSender<RoomActorEvent>,
-    upload_watchers: UploadWatchers,
-    tasks: TaskRegistry,
-    session_changes: Option<tokio::sync::broadcast::Receiver<SessionChange>>,
-    initial_history_limit: u16,
-    room_command_capacity: usize,
-    max_media_bytes: usize,
-    media: Arc<Mutex<MediaRegistry>>,
-    notification_commands: mpsc::Sender<CommandJob<NotificationCommand>>,
-    notification_command_receiver: Option<mpsc::Receiver<CommandJob<NotificationCommand>>>,
-    encryption_commands: mpsc::Sender<EncryptionWork>,
-    encryption_command_receiver: Option<mpsc::Receiver<EncryptionWork>>,
-    verification: Arc<Mutex<VerificationController>>,
-    room_commands: mpsc::Sender<RoomJob>,
-    room_command_receiver: Option<mpsc::Receiver<RoomJob>>,
-    global_account_gates: HashMap<String, oneshot::Receiver<()>>,
-    room_account_gates: HashMap<(OwnedRoomId, String), oneshot::Receiver<()>>,
-    media_flights: MediaFlights,
-    stop: Arc<tokio::sync::Notify>,
-}
-
-struct CommandJob<T> {
-    id: CommandId,
-    command: T,
-}
-
-enum EncryptionWork {
-    Command(CommandJob<EncryptionCommand>),
-}
-
-struct RoomJob {
-    id: CommandId,
-    command: RoomCommand,
-    reply: Option<oneshot::Sender<Result<OwnedRoomId, CommandResultError>>>,
-}
-
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-enum RoomMutationKey {
-    Room(OwnedRoomId),
-    Target(String),
-    Direct(ruma::OwnedUserId),
-    Independent(CommandId),
-}
-
-struct RoomJobCompletion {
-    key: RoomMutationKey,
-    id: CommandId,
-    reply: Option<oneshot::Sender<Result<OwnedRoomId, CommandResultError>>>,
-    result: Result<Option<OwnedRoomId>, CommandError>,
-}
-
-#[derive(Clone)]
-enum TaskContext {
-    Command {
-        id: CommandId,
-        kind: CommandKind,
-    },
-    Watcher(&'static str),
-    RoomActor {
-        room_id: OwnedRoomId,
-        generation: u64,
-    },
-}
-
-impl TaskContext {
-    fn label(&self) -> String {
-        match self {
-            Self::Command { id, kind } => format!("{kind:?} command {}", id.get()),
-            Self::Watcher(name) => (*name).to_owned(),
-            Self::RoomActor {
-                room_id,
-                generation,
-            } => format!("room actor {room_id} generation {generation}"),
-        }
-    }
-}
-
-struct TaskRegistry {
-    tasks: JoinSet<()>,
-    contexts: HashMap<TaskId, TaskContext>,
-}
-
-impl TaskRegistry {
-    fn new() -> Self {
-        Self {
-            tasks: JoinSet::new(),
-            contexts: HashMap::new(),
-        }
-    }
-
-    fn is_empty(&self) -> bool {
-        self.tasks.is_empty()
-    }
-
-    fn spawn(
-        &mut self,
-        context: TaskContext,
-        future: impl Future<Output = ()> + Send + 'static,
-    ) -> AbortHandle {
-        let handle = self.tasks.spawn(future);
-        self.contexts.insert(handle.id(), context);
-        handle
-    }
-
-    async fn join_next(&mut self) -> Option<(TaskContext, Result<(), tokio::task::JoinError>)> {
-        let result = self.tasks.join_next_with_id().await?;
-        let id = match &result {
-            Ok((id, ())) => *id,
-            Err(error) => error.id(),
-        };
-        let context = self
-            .contexts
-            .remove(&id)
-            .expect("every registered task has context");
-        Some((context, result.map(|(_, ())| ())))
-    }
-
-    async fn shutdown(&mut self) {
-        self.tasks.abort_all();
-        while self.tasks.join_next().await.is_some() {}
-        self.contexts.clear();
-    }
-}
-
-enum RoomActorState {
-    Opening {
-        generation: u64,
-        sender: mpsc::Sender<RoomActorRequest>,
-    },
-    Open {
-        generation: u64,
-        sender: mpsc::Sender<RoomActorRequest>,
-    },
-    Closing {
-        generation: u64,
-        pending: VecDeque<DeferredRoomLifecycle>,
-    },
-}
-
-enum DeferredRoomLifecycle {
-    Open(CommandId),
-    Close(CommandId),
-}
-
-impl RoomActorState {
-    const fn generation(&self) -> u64 {
-        match self {
-            Self::Opening { generation, .. }
-            | Self::Open { generation, .. }
-            | Self::Closing { generation, .. } => *generation,
-        }
-    }
-
-    fn sender(&self) -> Option<&mpsc::Sender<RoomActorRequest>> {
-        match self {
-            Self::Opening { sender, .. } | Self::Open { sender, .. } => Some(sender),
-            Self::Closing { .. } => None,
-        }
-    }
-}
-
-enum RoomActorEvent {
-    Ready {
-        room_id: OwnedRoomId,
-        generation: u64,
-    },
-    Exited {
-        room_id: OwnedRoomId,
-        generation: u64,
-    },
-}
-
-enum EngineActivity {
-    Request(Option<Box<DriverRequest>>),
-    Task(Option<(TaskContext, Result<(), tokio::task::JoinError>)>),
-    RoomActor(Option<RoomActorEvent>),
-}
-
-/// least recently seen goes first. stale order slots are skipped by stamp rather than hunted down
-struct MediaRegistry {
-    entries: HashMap<MediaId, (MediaRegistration, u64)>,
-    order: VecDeque<(MediaId, u64)>,
-    next_stamp: u64,
-    limit: usize,
-}
-
-impl MediaRegistry {
-    fn new(limit: usize) -> Self {
-        Self {
-            entries: HashMap::new(),
-            order: VecDeque::new(),
-            next_stamp: 0,
-            limit,
-        }
-    }
-
-    fn get(&self, id: &MediaId) -> Option<&MediaRegistration> {
-        self.entries.get(id).map(|(media, _)| media)
-    }
-
-    fn insert_all(&mut self, media: Vec<MediaRegistration>) {
-        for media in media {
-            let stamp = self.next_stamp;
-            self.next_stamp += 1;
-            self.order.push_back((media.id.clone(), stamp));
-            self.entries.insert(media.id.clone(), (media, stamp));
-        }
-        while self.entries.len() > self.limit {
-            let Some((id, stamp)) = self.order.pop_front() else {
-                break;
-            };
-            if self
-                .entries
-                .get(&id)
-                .is_some_and(|(_, current)| *current == stamp)
-            {
-                self.entries.remove(&id);
-            }
-        }
-        if self.order.len() > self.limit.saturating_mul(4) {
-            let entries = &self.entries;
-            self.order
-                .retain(|(id, stamp)| entries.get(id).is_some_and(|(_, current)| current == stamp));
-        }
-    }
-
-    fn release(&mut self, scope: &MediaScope) {
-        self.entries.retain(|id, _| !scope.owns(id));
-        let entries = &self.entries;
-        self.order.retain(|(id, _)| entries.contains_key(id));
-    }
-}
-
-enum RoomActorRequest {
-    Opened {
-        id: CommandId,
-    },
-    Execute {
-        id: CommandId,
-        command: TimelineCommand,
-    },
-    Close {
-        id: CommandId,
-    },
-}
-
-struct RoomActor {
-    room_id: OwnedRoomId,
-    generation: u64,
-    room: Room,
-    receiver: mpsc::Receiver<RoomActorRequest>,
-    events: EventSender,
-    engine_events: mpsc::UnboundedSender<RoomActorEvent>,
-    media: Arc<Mutex<MediaRegistry>>,
-    initial_history_limit: u16,
-    open_ids: Vec<CommandId>,
-    background: JoinSet<(CommandId, Result<(), CommandError>)>,
-    background_ids: HashMap<TaskId, CommandId>,
-}
-
-type BackgroundResult =
-    Result<(TaskId, (CommandId, Result<(), CommandError>)), tokio::task::JoinError>;
-type BackgroundWork = std::pin::Pin<Box<dyn Future<Output = Result<(), CommandError>> + Send>>;
-
-/// network-bound work runs beside the actor so one slow redaction doesn't queue the room behind it
-enum TimelineOutcome {
-    Done(Result<(), CommandError>),
-    Background(BackgroundWork),
-}
-
-struct TimelineSession {
-    id: TimelineId,
-    timeline: Arc<Timeline>,
-    events: EventSender,
-    watcher: JoinHandle<()>,
-    media: Arc<Mutex<MediaRegistry>>,
-    current_user_id: Option<ruma::OwnedUserId>,
-    scope: MediaScope,
-    pagination_ids: Arc<Mutex<HashSet<CommandId>>>,
-    pagination_sender: mpsc::Sender<PaginationRequest>,
-    pagination_worker: JoinHandle<()>,
-    pagination_results: Option<mpsc::UnboundedSender<(CommandId, Result<(), CommandError>)>>,
-    pagination_result_task: JoinHandle<()>,
-}
-
-struct PaginationRequest {
-    timeline: Arc<Timeline>,
-    events: EventSender,
-    timeline_id: TimelineId,
-    limit: u16,
-    command_id: Option<CommandId>,
-    results: mpsc::UnboundedSender<(CommandId, Result<(), CommandError>)>,
-}
-
-impl TimelineSession {
-    async fn start(
-        id: TimelineId,
-        timeline: Timeline,
-        events: EventSender,
-        media: Arc<Mutex<MediaRegistry>>,
-        current_user_id: Option<ruma::OwnedUserId>,
-        initial_history_limit: u16,
-    ) -> Result<Self, SendEventError> {
-        let timeline = Arc::new(timeline);
-        let scope = MediaScope::new();
-        let watcher = start_timeline_watcher(
-            id.clone(),
-            timeline.clone(),
-            events.clone(),
-            media.clone(),
-            current_user_id.clone(),
-            scope.clone(),
-        )
-        .await?;
-
-        let (pagination_sender, mut pagination_receiver) = mpsc::channel::<PaginationRequest>(32);
-        let pagination_worker = tokio::spawn(async move {
-            while let Some(request) = pagination_receiver.recv().await {
-                let command_id = request.command_id;
-                let results = request.results.clone();
-                if AssertUnwindSafe(run_pagination(request))
-                    .catch_unwind()
-                    .await
-                    .is_err()
-                {
-                    tracing::warn!(?command_id, "pagination task panicked");
-                    if let Some(id) = command_id {
-                        let _ = results.send((
-                            id,
-                            Err(CommandError::new(
-                                CommandErrorKind::Timeline,
-                                "pagination failed",
-                            )),
-                        ));
-                    }
-                }
-            }
-        });
-        let pagination_ids = Arc::new(Mutex::new(HashSet::new()));
-        let (pagination_results, mut result_receiver) = mpsc::unbounded_channel();
-        let result_events = events.clone();
-        let result_ids = pagination_ids.clone();
-        let pagination_result_task = tokio::spawn(async move {
-            while let Some((id, result)) = result_receiver.recv().await {
-                if result_ids.lock().await.remove(&id) {
-                    let _ = emit_command_result(&result_events, id, CommandKind::Timeline, result)
-                        .await;
-                }
-            }
-        });
-
-        let mut session = Self {
-            id,
-            timeline,
-            events,
-            watcher,
-            media,
-            current_user_id,
-            scope,
-            pagination_sender,
-            pagination_worker,
-            pagination_ids,
-            pagination_results: Some(pagination_results),
-            pagination_result_task,
-        };
-        if initial_history_limit > 0 {
-            session.paginate(initial_history_limit, None).await;
-        }
-        Ok(session)
-    }
-
-    async fn resync(&mut self) -> Result<(), SendEventError> {
-        self.watcher.abort();
-        let _ = (&mut self.watcher).await;
-        self.watcher = start_timeline_watcher(
-            self.id.clone(),
-            self.timeline.clone(),
-            self.events.clone(),
-            self.media.clone(),
-            self.current_user_id.clone(),
-            self.scope.clone(),
-        )
-        .await?;
-        Ok(())
-    }
-
-    async fn paginate(&mut self, limit: u16, command_id: Option<CommandId>) {
-        if let Some(id) = command_id {
-            self.pagination_ids.lock().await.insert(id);
-        }
-        let request = PaginationRequest {
-            timeline: self.timeline.clone(),
-            events: self.events.clone(),
-            timeline_id: self.id.clone(),
-            limit,
-            command_id,
-            results: self
-                .pagination_results
-                .as_ref()
-                .expect("pagination session is open")
-                .clone(),
-        };
-        if let Err(error) = self.pagination_sender.try_send(request) {
-            let kind = match error {
-                mpsc::error::TrySendError::Full(_) => CommandErrorKind::QueueFull,
-                mpsc::error::TrySendError::Closed(_) => CommandErrorKind::TimelineNotOpen,
-            };
-            if let Some(id) = command_id {
-                self.pagination_ids.lock().await.remove(&id);
-                let _ = emit_command_result(
-                    &self.events,
-                    id,
-                    CommandKind::Timeline,
-                    Err(CommandError::new(kind, "pagination queue is unavailable")),
-                )
-                .await;
-            }
-        }
-    }
-
-    async fn close(mut self, kind: CommandErrorKind, message: &'static str) {
-        self.media.lock().await.release(&self.scope);
-        self.pagination_worker.abort();
-        let _ = (&mut self.pagination_worker).await;
-        drop(self.pagination_results.take());
-        let _ = (&mut self.pagination_result_task).await;
-        let pending = self.pagination_ids.lock().await.drain().collect::<Vec<_>>();
-        for id in pending {
-            let _ = emit_command_result(
-                &self.events,
-                id,
-                CommandKind::Timeline,
-                Err(CommandError::new(kind, message)),
-            )
-            .await;
-        }
-        self.watcher.abort();
-        let _ = (&mut self.watcher).await;
-    }
-}
-
-async fn start_timeline_watcher(
-    id: TimelineId,
-    timeline: Arc<Timeline>,
-    events: EventSender,
-    media: Arc<Mutex<MediaRegistry>>,
-    current_user_id: Option<ruma::OwnedUserId>,
-    scope: MediaScope,
-) -> Result<JoinHandle<()>, SendEventError> {
-    let (items, mut stream) = timeline.subscribe().await;
-    let normalised = normalise_timeline(items.iter(), current_user_id.as_deref(), &scope);
-    media.lock().await.insert_all(normalised.media);
-    events
-        .send(Event::TimelineReset {
-            timeline_id: id.clone(),
-            items: normalised.items,
-        })
-        .await?;
-    Ok(tokio::spawn(async move {
-        while let Some(diffs) = stream.next().await {
-            let normalised = normalise_timeline_diffs(diffs, current_user_id.as_deref(), &scope);
-            media.lock().await.insert_all(normalised.media);
-            if events
-                .send(Event::TimelineChanged {
-                    timeline_id: id.clone(),
-                    diffs: normalised.diffs,
-                })
-                .await
-                .is_err()
-            {
-                tracing::debug!(
-                    ?id,
-                    "timeline watcher stopped because the event receiver closed"
-                );
-                return;
-            }
-        }
-        tracing::debug!(?id, "timeline watcher stopped");
-    }))
-}
-
-impl Drop for TimelineSession {
-    fn drop(&mut self) {
-        self.watcher.abort();
-        self.pagination_worker.abort();
-        self.pagination_result_task.abort();
-    }
-}
-
-impl Engine {
-    pub async fn from_client(
-        client: Client,
-        config: EngineConfig,
-    ) -> Result<(Self, ClientHandle, EventStream), EngineError> {
-        if client.user_id().is_none() {
-            return Err(EngineError::Unauthenticated);
-        }
-        if config.command_capacity == 0
-            || config.event_capacity == 0
-            || config.max_media_sources == 0
-        {
-            return Err(EngineError::ZeroCapacity);
-        }
-        let session_changes = client.subscribe_to_session_changes();
-        let sync = Arc::new(
-            SyncService::builder(client.clone())
-                .with_offline_mode()
-                .build()
-                .await
-                .map_err(EngineError::SyncService)?,
-        );
-        let (handle, port, events) = transport_pair(
-            client.clone(),
-            sync.clone(),
-            config.command_capacity,
-            config.event_capacity,
-        );
-        client.send_queue().enable_upload_progress(true);
-        let (room_actor_event_sender, room_actor_events) = mpsc::unbounded_channel();
-        let (notification_commands, notification_command_receiver) =
-            mpsc::channel(config.command_capacity);
-        let (encryption_commands, encryption_command_receiver) =
-            mpsc::channel(config.command_capacity);
-        let (room_commands, room_command_receiver) = mpsc::channel(config.command_capacity);
-        Ok((
-            Self {
-                client,
-                sync,
-                port,
-                rooms: HashMap::new(),
-                next_room_generation: 0,
-                room_actor_events,
-                room_actor_event_sender,
-                upload_watchers: HashMap::new(),
-                tasks: TaskRegistry::new(),
-                session_changes: Some(session_changes),
-                initial_history_limit: config.initial_history_limit,
-                room_command_capacity: config.command_capacity,
-                max_media_bytes: config.max_media_bytes,
-                media: Arc::new(Mutex::new(MediaRegistry::new(config.max_media_sources))),
-                notification_commands,
-                notification_command_receiver: Some(notification_command_receiver),
-                encryption_commands,
-                encryption_command_receiver: Some(encryption_command_receiver),
-                verification: Arc::new(Mutex::new(VerificationController::default())),
-                room_commands,
-                room_command_receiver: Some(room_command_receiver),
-                global_account_gates: HashMap::new(),
-                room_account_gates: HashMap::new(),
-                media_flights: Arc::new(Mutex::new(HashMap::new())),
-                stop: Arc::new(tokio::sync::Notify::new()),
-            },
-            handle,
-            events,
-        ))
-    }
-
-    pub async fn run(mut self) -> Result<(), EngineError> {
-        let sender = self.port.event_sender();
-        let user_id = self
-            .client
-            .user_id()
-            .expect("authentication was checked during construction")
-            .to_owned();
-        if sender.send(Event::Authenticated { user_id }).await.is_err() {
-            self.shutdown().await;
-            return Err(EngineError::EventReceiverClosed);
-        }
-        self.port
-            .connection_sender()
-            .send_replace(ConnectionState::Connecting);
-        if sender
-            .send(Event::ConnectionChanged(ConnectionState::Connecting))
-            .await
-            .is_err()
-        {
-            self.shutdown().await;
-            return Err(EngineError::EventReceiverClosed);
-        }
-        self.start_watchers();
-        self.start_domain_workers();
-        self.sync.start().await;
-        let mut terminal_error = None;
-
-        loop {
-            let activity = tokio::select! {
-                biased;
-                _ = sender.closed() => {
-                    terminal_error = Some(EngineError::EventReceiverClosed);
-                    break;
-                }
-                () = self.stop.notified() => break,
-                request = self.port.recv() => EngineActivity::Request(request.map(Box::new)),
-                completed = self.tasks.join_next(), if !self.tasks.is_empty() => {
-                    EngineActivity::Task(completed)
-                }
-                event = self.room_actor_events.recv() => EngineActivity::RoomActor(event),
-            };
-            match activity {
-                EngineActivity::Request(Some(request)) => {
-                    let Some(envelope) = self.dispatch_request(*request).await else {
-                        continue;
-                    };
-                    let id = envelope.id;
-                    let command = envelope.command;
-                    if matches!(command, Command::Lifecycle(LifecycleCommand::Shutdown)) {
-                        let _ =
-                            emit_command_result(&sender, id, CommandKind::Lifecycle, Ok(())).await;
-                        break;
-                    }
-                    let kind = command.kind();
-                    tracing::debug!(?id, ?kind, "dispatching command");
-                    let result = self.execute(id, command).await;
-                    if Self::emit_sync_result(&sender, id, kind, result)
-                        .await
-                        .is_err()
-                    {
-                        terminal_error = Some(EngineError::EventReceiverClosed);
-                        break;
-                    }
-                }
-                EngineActivity::Request(None) => break,
-                EngineActivity::Task(Some((context, result))) => {
-                    if let Err(error) = result
-                        && error.is_panic()
-                    {
-                        match context {
-                            TaskContext::Command { id, kind } => {
-                                if sender
-                                    .send(Event::CommandFailed(CommandFailure {
-                                        id,
-                                        command: kind,
-                                        kind: CommandErrorKind::Other,
-                                        message: "command task panicked".to_owned(),
-                                    }))
-                                    .await
-                                    .is_err()
-                                {
-                                    terminal_error = Some(EngineError::EventReceiverClosed);
-                                    break;
-                                }
-                            }
-                            context => {
-                                terminal_error = Some(EngineError::TaskPanicked {
-                                    task: context.label(),
-                                });
-                                break;
-                            }
-                        }
-                    }
-                }
-                EngineActivity::Task(None) => {}
-                EngineActivity::RoomActor(Some(event)) => {
-                    if let Err(error) = self.handle_room_actor_event(event).await {
-                        terminal_error = Some(error);
-                        break;
-                    }
-                }
-                EngineActivity::RoomActor(None) => {
-                    terminal_error = Some(EngineError::TaskPanicked {
-                        task: "room actor event channel".to_owned(),
-                    });
-                    break;
-                }
-            }
-        }
-
-        if let Some(error) = terminal_error.as_ref() {
-            let _ = sender.send(Event::Failed(error.failure())).await;
-        }
-        self.shutdown().await;
-        let _ = sender.send(Event::Stopped).await;
-        if let Some(error) = terminal_error {
-            Err(error)
-        } else {
-            Ok(())
-        }
-    }
-
-    async fn emit_sync_result(
-        sender: &EventSender,
-        id: CommandId,
-        kind: CommandKind,
-        result: Result<bool, CommandError>,
-    ) -> Result<(), SendEventError> {
-        match result {
-            Ok(true) => Ok(()),
-            Ok(false) => emit_command_result(sender, id, kind, Ok(())).await,
-            Err(error) => {
-                tracing::warn!(?id, ?kind, error = ?error, "command failed");
-                emit_command_result(sender, id, kind, Err(error)).await?;
-                Ok(())
-            }
-        }
-    }
-
-    fn spawn_logout(&mut self, id: CommandId) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        let stop = self.stop.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Account,
-            },
-            async move {
-                match client
-                    .logout()
-                    .await
-                    .map(|_| ())
-                    .map_err(|source| CommandError::from_sdk("logout failed", source))
-                {
-                    Ok(()) => {
-                        let _ =
-                            emit_command_result(&events, id, CommandKind::Account, Ok(())).await;
-                        let _ = events.send(Event::LoggedOut).await;
-                        stop.notify_one();
-                    }
-                    Err(error) => {
-                        let _ = emit_command_result(&events, id, CommandKind::Account, Err(error))
-                            .await;
-                    }
-                }
-            },
-        );
-    }
-
-    async fn dispatch_request(&mut self, request: DriverRequest) -> Option<CommandEnvelope> {
-        match request {
-            DriverRequest::Command(command) => Some(command),
-            DriverRequest::DeleteDevices {
-                id,
-                device_ids,
-                auth,
-                reply,
-            } => {
-                self.spawn_delete_devices(id, device_ids, auth, Some(reply));
-                None
-            }
-            DriverRequest::RoomResult { id, command, reply } => {
-                if let Err(error) = self.spawn_room_command_with_reply(id, command, Some(reply)) {
-                    tracing::warn!(?id, error = ?error, "room result request failed");
-                }
-                None
-            }
-            DriverRequest::SetGlobalAccountData {
-                event_type,
-                content,
-                reply,
-            } => {
-                self.spawn_global_account_data_write(event_type, content, reply);
-                None
-            }
-            DriverRequest::SetRoomAccountData {
-                room_id,
-                event_type,
-                content,
-                reply,
-            } => {
-                self.spawn_room_account_data_write(room_id, event_type, content, reply);
-                None
-            }
-        }
-    }
-
-    fn spawn_mark_read(&mut self, id: CommandId, timeline_id: TimelineId, event_id: OwnedEventId) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Room,
-            },
-            async move {
-                let result = mark_read(&client, &timeline_id, event_id).await;
-                let _ = emit_command_result(&events, id, CommandKind::Room, result).await;
-            },
-        );
-    }
-
-    fn spawn_typing(&mut self, id: CommandId, room_id: OwnedRoomId, typing: bool) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Room,
-            },
-            async move {
-                let result = set_typing(&client, &room_id, typing).await;
-                let _ = emit_command_result(&events, id, CommandKind::Room, result).await;
-            },
-        );
-    }
-
-    fn spawn_cancel_send(
-        &mut self,
-        id: CommandId,
-        room_id: OwnedRoomId,
-        transaction_id: matrix_sdk::ruma::OwnedTransactionId,
-    ) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Room,
-            },
-            async move {
-                let result = cancel_send(&client, &room_id, &transaction_id).await;
-                let _ = emit_command_result(&events, id, CommandKind::Room, result).await;
-            },
-        );
-    }
-
-    fn spawn_retry_send(
-        &mut self,
-        id: CommandId,
-        room_id: OwnedRoomId,
-        transaction_id: matrix_sdk::ruma::OwnedTransactionId,
-    ) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Room,
-            },
-            async move {
-                let result = retry_send(&client, &room_id, &transaction_id).await;
-                let _ = emit_command_result(&events, id, CommandKind::Room, result).await;
-            },
-        );
-    }
-
-    fn spawn_delete_devices(
-        &mut self,
-        id: CommandId,
-        device_ids: Vec<OwnedDeviceId>,
-        auth: Option<InteractiveAuth>,
-        reply: Option<oneshot::Sender<Result<InteractiveAuthOutcome, CommandResultError>>>,
-    ) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Account,
-            },
-            async move {
-                let auth = match auth {
-                    Some(auth) => match auth.into_sdk(
-                        client
-                            .user_id()
-                            .expect("authentication was checked during construction"),
-                    ) {
-                        Ok(auth) => Some(auth),
-                        Err(message) => {
-                            let failure = CommandFailure {
-                                id,
-                                command: CommandKind::Account,
-                                kind: CommandErrorKind::Other,
-                                message: format!(
-                                    "interactive authentication data is invalid, {message}"
-                                ),
-                            };
-                            if let Some(reply) = reply {
-                                let _ =
-                                    reply.send(Err(CommandResultError::Failed(failure.clone())));
-                            } else {
-                                let _ = events.send(Event::CommandFailed(failure)).await;
-                            }
-                            return;
-                        }
-                    },
-                    None => None,
-                };
-                let result = client.delete_devices(&device_ids, auth).await;
-
-                match result {
-                    Ok(_) => {
-                        if let Some(reply) = reply {
-                            let _ = reply.send(Ok(InteractiveAuthOutcome::Completed));
-                        } else {
-                            let _ = emit_command_result(&events, id, CommandKind::Account, Ok(()))
-                                .await;
-                        }
-                    }
-                    Err(source) => {
-                        if let Some(info) = source.as_uiaa_response() {
-                            let challenge = InteractiveAuthChallenge::from(info);
-                            if let Some(reply) = reply {
-                                let _ =
-                                    reply.send(Ok(InteractiveAuthOutcome::Challenge(challenge)));
-                            } else {
-                                let _ = events
-                                    .send(Event::InteractiveAuthRequired {
-                                        id,
-                                        command: CommandKind::Account,
-                                        challenge: challenge.clone(),
-                                    })
-                                    .await;
-                                let _ = events
-                                    .send(Event::CommandFailed(CommandFailure {
-                                        id,
-                                        command: CommandKind::Account,
-                                        kind: CommandErrorKind::InteractiveAuthRequired,
-                                        message: "interactive authentication is required"
-                                            .to_owned(),
-                                    }))
-                                    .await;
-                            }
-                        } else {
-                            let error = CommandError::from_http("deleting devices failed", source);
-                            let failure = CommandFailure {
-                                id,
-                                command: CommandKind::Account,
-                                kind: error.kind,
-                                message: error.to_string(),
-                            };
-                            if let Some(reply) = reply {
-                                let _ =
-                                    reply.send(Err(CommandResultError::Failed(failure.clone())));
-                            } else {
-                                let _ = events.send(Event::CommandFailed(failure)).await;
-                            }
-                        }
-                    }
-                }
-            },
-        );
-    }
-
-    fn spawn_rename_device(
-        &mut self,
-        id: CommandId,
-        device_id: OwnedDeviceId,
-        display_name: String,
-    ) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Account,
-            },
-            async move {
-                match client.rename_device(&device_id, &display_name).await {
-                    Ok(_) => {
-                        let _ = events
-                            .send(Event::CommandSucceeded {
-                                id,
-                                command: CommandKind::Account,
-                            })
-                            .await;
-                    }
-                    Err(source) => {
-                        let error = CommandError::from_http("renaming device failed", source);
-                        let _ = events
-                            .send(Event::CommandFailed(CommandFailure {
-                                id,
-                                command: CommandKind::Account,
-                                kind: error.kind,
-                                message: error.to_string(),
-                            }))
-                            .await;
-                    }
-                }
-            },
-        );
-    }
-
-    fn spawn_global_account_data_write(
-        &mut self,
-        event_type: GlobalAccountDataEventType,
-        content: Raw<AnyGlobalAccountDataEventContent>,
-        reply: oneshot::Sender<Result<(), ClientQueryError>>,
-    ) {
-        let (done, next) = oneshot::channel();
-        let previous = self
-            .global_account_gates
-            .insert(event_type.to_string(), next);
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Watcher("global account data writer"),
-            async move {
-                if let Some(previous) = previous {
-                    let _ = previous.await;
-                }
-                let result = client
-                    .account()
-                    .set_account_data_raw(event_type, content)
-                    .await
-                    .map(|_| ())
-                    .map_err(ClientQueryError::Sdk);
-                let _ = reply.send(result);
-                let _ = done.send(());
-            },
-        );
-    }
-
-    fn spawn_room_account_data_write(
-        &mut self,
-        room_id: OwnedRoomId,
-        event_type: RoomAccountDataEventType,
-        content: Raw<matrix_sdk::ruma::events::AnyRoomAccountDataEventContent>,
-        reply: oneshot::Sender<Result<(), ClientQueryError>>,
-    ) {
-        let (done, next) = oneshot::channel();
-        let previous = self
-            .room_account_gates
-            .insert((room_id.clone(), event_type.to_string()), next);
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Watcher("room account data writer"),
-            async move {
-                if let Some(previous) = previous {
-                    let _ = previous.await;
-                }
-                let result = match client.get_room(&room_id) {
-                    Some(room) => room
-                        .set_account_data_raw(event_type, content)
-                        .await
-                        .map(|_| ())
-                        .map_err(ClientQueryError::Sdk),
-                    None => Err(ClientQueryError::RoomUnknown(room_id)),
-                };
-                let _ = reply.send(result);
-                let _ = done.send(());
-            },
-        );
-    }
-
-    fn start_domain_workers(&mut self) {
-        let mut notification_commands = self
-            .notification_command_receiver
-            .take()
-            .expect("notification worker has not started");
-        let notification_client = self.client.clone();
-        let notification_events = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Watcher("notification command worker"),
-            async move {
-                while let Some(CommandJob { id, command }) = notification_commands.recv().await {
-                    let result = AssertUnwindSafe(execute_notification_command(
-                        &notification_client,
-                        command,
-                    ))
-                    .catch_unwind()
-                    .await
-                    .unwrap_or_else(|_| {
-                        Err(CommandError::new(
-                            CommandErrorKind::Other,
-                            "notification command panicked",
-                        ))
-                    });
-                    let _ = emit_command_result(
-                        &notification_events,
-                        id,
-                        CommandKind::Notification,
-                        result,
-                    )
-                    .await;
-                }
-            },
-        );
-
-        let mut encryption_commands = self
-            .encryption_command_receiver
-            .take()
-            .expect("encryption worker has not started");
-        let encryption_client = self.client.clone();
-        let encryption_events = self.port.event_sender();
-        let verification = self.verification.clone();
-        self.tasks.spawn(
-            TaskContext::Watcher("encryption command worker"),
-            async move {
-                while let Some(work) = encryption_commands.recv().await {
-                    match work {
-                        EncryptionWork::Command(CommandJob { id, command }) => {
-                            if matches!(
-                                command,
-                                EncryptionCommand::Recover(_)
-                                    | EncryptionCommand::RecoverKeyBackup(_)
-                            ) {
-                                let result = AssertUnwindSafe(execute_encryption_command(
-                                    &encryption_client,
-                                    &encryption_events,
-                                    &mut VerificationController::default(),
-                                    command,
-                                ))
-                                .catch_unwind()
-                                .await
-                                .unwrap_or_else(|_| {
-                                    Err(CommandError::new(
-                                        CommandErrorKind::Other,
-                                        "encryption command panicked",
-                                    ))
-                                });
-                                let _ = emit_command_result(
-                                    &encryption_events,
-                                    id,
-                                    CommandKind::Encryption,
-                                    result,
-                                )
-                                .await;
-                                continue;
-                            }
-                            let is_key_backup = matches!(
-                                command,
-                                EncryptionCommand::CreateKeyBackup
-                                    | EncryptionCommand::EnableKeyBackup
-                                    | EncryptionCommand::DisableKeyBackup { .. }
-                            );
-                            let result = if is_key_backup {
-                                AssertUnwindSafe(execute_key_backup_command(
-                                    &encryption_client,
-                                    command,
-                                ))
-                                .catch_unwind()
-                                .await
-                                .unwrap_or_else(|_| {
-                                    Err(CommandError::new(
-                                        CommandErrorKind::Other,
-                                        "encryption command panicked",
-                                    ))
-                                })
-                            } else {
-                                let mut verification = verification.lock().await;
-                                let result = AssertUnwindSafe(execute_encryption_command(
-                                    &encryption_client,
-                                    &encryption_events,
-                                    &mut verification,
-                                    command,
-                                ))
-                                .catch_unwind()
-                                .await
-                                .unwrap_or_else(|_| {
-                                    Err(CommandError::new(
-                                        CommandErrorKind::Other,
-                                        "encryption command panicked",
-                                    ))
-                                });
-                                drop(verification);
-                                result
-                            };
-                            let _ = emit_command_result(
-                                &encryption_events,
-                                id,
-                                CommandKind::Encryption,
-                                result,
-                            )
-                            .await;
-                        }
-                    }
-                }
-            },
-        );
-
-        let room_commands = self
-            .room_command_receiver
-            .take()
-            .expect("room command worker has not started");
-        let room_client = self.client.clone();
-        let room_events = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Watcher("room command worker"),
-            run_room_command_worker(
-                room_client,
-                room_events,
-                room_commands,
-                self.room_command_capacity,
-            ),
-        );
-    }
-
-    fn start_watchers(&mut self) {
-        let mut session_changes = self
-            .session_changes
-            .take()
-            .expect("session watcher has not started");
-        let session_sender = self.port.event_sender();
-        let stop = self.stop.clone();
-        self.tasks
-            .spawn(TaskContext::Watcher("session change watcher"), async move {
-                loop {
-                    let event = match session_changes.recv().await {
-                        Ok(SessionChange::TokensRefreshed) => Event::SessionTokensChanged,
-                        Ok(SessionChange::UnknownToken(data)) => {
-                            let _ = session_sender
-                                .send(Event::SessionAccessRejected {
-                                    soft_logout: data.soft_logout,
-                                })
-                                .await;
-                            stop.notify_one();
-                            break;
-                        }
-                        Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => {
-                            Event::SessionTokensChanged
-                        }
-                        Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
-                    };
-                    if session_sender.send(event).await.is_err() {
-                        break;
-                    }
-                }
-            });
-
-        let mut sync_states = self.sync.state();
-        let state_sender = self.port.event_sender();
-        let connection_sender = self.port.connection_sender();
-        let sync = self.sync.clone();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Watcher("connection state watcher"),
-            async move {
-                let mut backoff = SYNC_RESTART_MIN;
-                while let Some(state) = sync_states.next().await {
-                    let (state, restart) = match state {
-                        SyncState::Idle => (ConnectionState::Idle, false),
-                        SyncState::Running => {
-                            backoff = SYNC_RESTART_MIN;
-                            // the sdk parks a room queue on any send error and never unparks it
-                            client.send_queue().set_enabled(true).await;
-                            (ConnectionState::Online, false)
-                        }
-                        SyncState::Offline => (ConnectionState::Offline, false),
-                        SyncState::Terminated => (ConnectionState::Offline, true),
-                        SyncState::Error(error) => {
-                            tracing::warn!(error = %error, "sync service reported an error");
-                            (ConnectionState::Offline, true)
-                        }
-                    };
-                    if *connection_sender.borrow() != state {
-                        connection_sender.send_replace(state);
-                        if state_sender
-                            .send(Event::ConnectionChanged(state))
-                            .await
-                            .is_err()
-                        {
-                            break;
-                        }
-                    }
-                    if restart {
-                        tokio::time::sleep(backoff).await;
-                        backoff = (backoff * 2).min(SYNC_RESTART_MAX);
-                        sync.start().await;
-                    }
-                }
-            },
-        );
-
-        let client = self.client.clone();
-        let online = self.port.connection_sender().subscribe();
-        self.tasks
-            .spawn(TaskContext::Watcher("send queue watcher"), async move {
-                let mut errors = client.send_queue().subscribe_errors();
-                let mut retries = JoinSet::new();
-                loop {
-                    let error = tokio::select! {
-                        error = errors.recv() => error,
-                        Some(_) = retries.join_next(), if !retries.is_empty() => continue,
-                    };
-                    match error {
-                        Ok(error) if error.is_recoverable => {
-                            let client = client.clone();
-                            let online = online.clone();
-                            retries.spawn(async move {
-                                tokio::time::sleep(SEND_QUEUE_RETRY).await;
-                                if *online.borrow() == ConnectionState::Online
-                                    && let Some(room) = client.get_room(&error.room_id)
-                                {
-                                    room.send_queue().set_enabled(true);
-                                }
-                            });
-                        }
-                        Ok(_) | Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => {}
-                        Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
-                    }
-                }
-            });
-
-        let client = self.client.clone();
-        let encryption_sender = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Watcher("encryption state watcher"),
-            async move {
-            let Some(device_id) = client.device_id().map(ToOwned::to_owned) else {
-                tracing::warn!("encryption watcher stopped because the client has no device id");
-                return;
-            };
-            let recovery = client.encryption().recovery();
-            let backups = client.encryption().backups();
-            let mut recovery_stream = recovery.state_stream();
-            let mut backup_stream = backups.state_stream();
-            let mut verification_stream = client.encryption().verification_state();
-            let mut recovery_state = recovery.state();
-            let mut backup_state = backups.state();
-            let mut verification_state = verification_stream.get();
-            if encryption_sender
-                .send(Event::EncryptionChanged(encryption_state(
-                    device_id.clone(),
-                    recovery_state,
-                    verification_state,
-                    backup_state,
-                )))
-                .await
-                .is_err()
-            {
-                tracing::debug!(
-                    "encryption watcher stopped because the event receiver closed"
-                );
-                return;
-            }
-            loop {
-                tokio::select! {
-                    update = recovery_stream.next() => {
-                        let Some(update) = update else {
-                            tracing::debug!("encryption watcher stopped because the recovery stream ended");
-                            break;
-                        };
-                        recovery_state = update;
-                    }
-                    update = verification_stream.next() => {
-                        let Some(update) = update else {
-                            tracing::debug!("encryption watcher stopped because the verification stream ended");
-                            break;
-                        };
-                        verification_state = update;
-                    }
-                    update = backup_stream.next() => {
-                        let Some(update) = update else {
-                            tracing::debug!("backup watcher stopped because the backup state stream ended");
-                            break;
-                        };
-                        backup_state = update.unwrap_or_else(|_| backups.state());
-                    }
-                }
-                if encryption_sender
-                    .send(Event::EncryptionChanged(encryption_state(
-                        device_id.clone(),
-                        recovery_state,
-                        verification_state,
-                        backup_state,
-                    )))
-                    .await
-                    .is_err()
-                {
-                    tracing::debug!(
-                        "encryption watcher stopped because the event receiver closed"
-                    );
-                    break;
-                }
-            }
-            },
-        );
-
-        let client = self.client.clone();
-        let room_sender = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Watcher("room list watcher"),
-            async move {
-            let (_, mut room_stream) = client.rooms_stream();
-            let mut info_stream = client.room_info_notable_update_receiver();
-            if room_sender.send(Event::RoomsChanged).await.is_err() {
-                tracing::debug!("room watcher stopped because the event receiver closed");
-                return;
-            }
-            loop {
-                tokio::select! {
-                    update = room_stream.next() => {
-                        if update.is_none() {
-                            tracing::debug!("room watcher stopped because the room stream ended");
-                            break;
-                        }
-                    }
-                    update = info_stream.recv() => {
-                        if update.is_err() && info_stream.is_closed() {
-                            tracing::debug!("room watcher stopped because the room info stream ended");
-                            break;
-                        }
-                    }
-                }
-                if room_sender.send(Event::RoomsChanged).await.is_err() {
-                    tracing::debug!("room watcher stopped because the event receiver closed");
-                    break;
-                }
-            }
-            },
-        );
-
-        let client = self.client.clone();
-        let notification_sender = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Watcher("notification settings watcher"),
-            async move {
-                let settings = client.notification_settings().await;
-                let mut changes = settings.subscribe_to_changes();
-                while let Ok(()) | Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) =
-                    changes.recv().await
-                {
-                    if notification_sender
-                        .send(Event::NotificationSettingsChanged)
-                        .await
-                        .is_err()
-                    {
-                        break;
-                    }
-                }
-            },
-        );
-    }
-
-    async fn execute(&mut self, id: CommandId, command: Command) -> Result<bool, CommandError> {
-        match command {
-            Command::Account(AccountCommand::Logout) => {
-                self.spawn_logout(id);
-                Ok(true)
-            }
-            Command::Account(AccountCommand::RenameDevice {
-                device_id,
-                display_name,
-            }) => {
-                self.spawn_rename_device(id, device_id, display_name);
-                Ok(true)
-            }
-            Command::Account(AccountCommand::DeleteDevices { device_ids, auth }) => {
-                self.spawn_delete_devices(id, device_ids, auth, None);
-                Ok(true)
-            }
-            Command::Room(RoomCommand::Open(room_id)) => self.open_room(id, room_id).await,
-            Command::Room(RoomCommand::Close(room_id)) => self.close_room(id, &room_id).await,
-            Command::Room(RoomCommand::SetTyping { room_id, typing }) => {
-                self.spawn_typing(id, room_id, typing);
-                Ok(true)
-            }
-            Command::Room(RoomCommand::Join { room, via }) => {
-                self.spawn_room_command(id, RoomCommand::Join { room, via })
-            }
-            Command::Room(RoomCommand::Leave(room_id)) => {
-                self.spawn_room_command(id, RoomCommand::Leave(room_id))
-            }
-            Command::Room(RoomCommand::Forget(room_id)) => {
-                self.spawn_room_command(id, RoomCommand::Forget(room_id))
-            }
-            Command::Room(RoomCommand::AcceptInvite(room_id)) => {
-                self.spawn_room_command(id, RoomCommand::AcceptInvite(room_id))
-            }
-            Command::Room(RoomCommand::RejectInvite(room_id)) => {
-                self.spawn_room_command(id, RoomCommand::RejectInvite(room_id))
-            }
-            Command::Room(command @ RoomCommand::InviteUser { .. })
-            | Command::Room(command @ RoomCommand::KickUser { .. })
-            | Command::Room(command @ RoomCommand::BanUser { .. })
-            | Command::Room(command @ RoomCommand::UnbanUser { .. })
-            | Command::Room(command @ RoomCommand::SetPowerLevels { .. })
-            | Command::Room(command @ RoomCommand::SetUserPowerLevel { .. }) => {
-                self.spawn_room_command(id, command)
-            }
-            Command::Room(RoomCommand::Create(options)) => {
-                self.spawn_room_command(id, RoomCommand::Create(options))
-            }
-            Command::Room(RoomCommand::CreateDirect(user_id)) => {
-                self.spawn_room_command(id, RoomCommand::CreateDirect(user_id))
-            }
-            Command::Room(RoomCommand::CancelSend {
-                room_id,
-                transaction_id,
-            }) => {
-                self.spawn_cancel_send(id, room_id, transaction_id);
-                Ok(true)
-            }
-            Command::Room(RoomCommand::RetrySend {
-                room_id,
-                transaction_id,
-            }) => {
-                self.spawn_retry_send(id, room_id, transaction_id);
-                Ok(true)
-            }
-            Command::Timeline(command) => self.route_timeline(id, command),
-            Command::Media(MediaCommand::Fetch { id: media_id, size }) => {
-                self.spawn_media_fetch(id, media_id, size);
-                Ok(true)
-            }
-            Command::Media(MediaCommand::Upload {
-                timeline_id,
-                filename,
-                mimetype,
-                bytes,
-                caption,
-            }) => {
-                let mut upload = AttachmentUpload::new(timeline_id, filename, mimetype, bytes);
-                upload.caption = caption;
-                self.spawn_media_upload(id, upload).await.map(|()| true)
-            }
-            Command::Media(MediaCommand::UploadAttachment(upload)) => {
-                self.spawn_media_upload(id, upload).await.map(|()| true)
-            }
-            Command::Encryption(command) => {
-                self.encryption_commands
-                    .try_send(EncryptionWork::Command(CommandJob { id, command }))
-                    .map_err(|error| domain_queue_error(error, "encryption"))?;
-                Ok(true)
-            }
-            Command::Notification(command) => {
-                self.notification_commands
-                    .try_send(CommandJob { id, command })
-                    .map_err(|error| domain_queue_error(error, "notification"))?;
-                Ok(true)
-            }
-            Command::Lifecycle(LifecycleCommand::Shutdown) => Ok(false),
-        }
-    }
-
-    async fn open_room(
-        &mut self,
-        id: CommandId,
-        room_id: OwnedRoomId,
-    ) -> Result<bool, CommandError> {
-        match self.rooms.get_mut(&room_id) {
-            Some(RoomActorState::Opening { sender, .. }) => {
-                send_room_actor_request(sender, RoomActorRequest::Opened { id })?;
-                return Ok(true);
-            }
-            Some(RoomActorState::Open { .. }) => return Ok(false),
-            Some(RoomActorState::Closing { pending, .. }) => {
-                if pending.len() >= self.room_command_capacity {
-                    return Err(CommandError::new(
-                        CommandErrorKind::RoomBusy,
-                        "room lifecycle queue is full",
-                    ));
-                }
-                pending.push_back(DeferredRoomLifecycle::Open(id));
-                return Ok(true);
-            }
-            None => {}
-        }
-        self.start_room_actor(room_id, vec![id]).await?;
-        Ok(true)
-    }
-
-    async fn start_room_actor(
-        &mut self,
-        room_id: OwnedRoomId,
-        open_ids: Vec<CommandId>,
-    ) -> Result<(), CommandError> {
-        let room = self.client.get_room(&room_id).ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::RoomUnknown,
-                "room is not available in the local store",
-            )
-        })?;
-        self.next_room_generation = self.next_room_generation.wrapping_add(1);
-        let generation = self.next_room_generation;
-        let (sender, receiver) = mpsc::channel(self.room_command_capacity);
-        let actor = RoomActor {
-            room_id: room_id.clone(),
-            generation,
-            room,
-            receiver,
-            events: self.port.event_sender(),
-            engine_events: self.room_actor_event_sender.clone(),
-            media: self.media.clone(),
-            initial_history_limit: self.initial_history_limit,
-            open_ids,
-            background: JoinSet::new(),
-            background_ids: HashMap::new(),
-        };
-        let current_user_id = self.client.user_id().map(ToOwned::to_owned);
-        self.rooms.insert(
-            room_id.clone(),
-            RoomActorState::Opening { generation, sender },
-        );
-        let actor_room_id = room_id.clone();
-        let engine_events = self.room_actor_event_sender.clone();
-        self.tasks.spawn(
-            TaskContext::RoomActor {
-                room_id: room_id.clone(),
-                generation,
-            },
-            async move {
-                actor.run(current_user_id).await;
-                let _ = engine_events.send(RoomActorEvent::Exited {
-                    room_id: actor_room_id,
-                    generation,
-                });
-            },
-        );
-        self.update_room_subscriptions().await;
-        Ok(())
-    }
-
-    fn spawn_room_command(
-        &mut self,
-        id: CommandId,
-        command: RoomCommand,
-    ) -> Result<bool, CommandError> {
-        self.spawn_room_command_with_reply(id, command, None)?;
-        Ok(true)
-    }
-
-    fn spawn_room_command_with_reply(
-        &mut self,
-        id: CommandId,
-        command: RoomCommand,
-        reply: Option<oneshot::Sender<Result<OwnedRoomId, CommandResultError>>>,
-    ) -> Result<(), CommandError> {
-        let job = RoomJob { id, command, reply };
-        self.room_commands.try_send(job).map_err(|error| {
-            let (job, kind, message) = match error {
-                mpsc::error::TrySendError::Full(job) => (
-                    job,
-                    CommandErrorKind::QueueFull,
-                    "room command queue is full",
-                ),
-                mpsc::error::TrySendError::Closed(job) => (
-                    job,
-                    CommandErrorKind::Other,
-                    "room command worker has stopped",
-                ),
-            };
-            let error = CommandError::new(kind, message);
-            if let Some(reply) = job.reply {
-                let _ = reply.send(Err(CommandResultError::Failed(CommandFailure {
-                    id: job.id,
-                    command: CommandKind::Room,
-                    kind: error.kind,
-                    message: error.to_string(),
-                })));
-            }
-            error
-        })
-    }
-
-    fn route_timeline(
-        &mut self,
-        id: CommandId,
-        command: TimelineCommand,
-    ) -> Result<bool, CommandError> {
-        let sender = self
-            .rooms
-            .get(command.room_id())
-            .and_then(RoomActorState::sender)
-            .cloned();
-        match (sender, command) {
-            (Some(sender), command) => {
-                send_room_actor_request(&sender, RoomActorRequest::Execute { id, command })?;
-            }
-            (
-                None,
-                TimelineCommand::MarkRead {
-                    timeline_id,
-                    event_id,
-                },
-            ) => self.spawn_mark_read(id, timeline_id, event_id),
-            (None, _) => {
-                return Err(CommandError::new(
-                    CommandErrorKind::RoomNotOpen,
-                    "room is not open",
-                ));
-            }
-        }
-        Ok(true)
-    }
-
-    async fn close_room(&mut self, id: CommandId, room_id: &RoomId) -> Result<bool, CommandError> {
-        let Some(state) = self.rooms.get_mut(room_id) else {
-            return Ok(false);
-        };
-        if let RoomActorState::Closing { pending, .. } = state {
-            if pending.len() >= self.room_command_capacity {
-                return Err(CommandError::new(
-                    CommandErrorKind::RoomBusy,
-                    "room lifecycle queue is full",
-                ));
-            }
-            pending.push_back(DeferredRoomLifecycle::Close(id));
-            return Ok(true);
-        }
-        let Some(sender) = state.sender().cloned() else {
-            return Ok(false);
-        };
-        let generation = state.generation();
-        send_room_actor_request(&sender, RoomActorRequest::Close { id })?;
-        self.rooms.insert(
-            room_id.to_owned(),
-            RoomActorState::Closing {
-                generation,
-                pending: VecDeque::new(),
-            },
-        );
-        self.update_room_subscriptions().await;
-        Ok(true)
-    }
-
-    async fn handle_room_actor_event(&mut self, event: RoomActorEvent) -> Result<(), EngineError> {
-        match event {
-            RoomActorEvent::Ready {
-                room_id,
-                generation,
-            } => {
-                let stale = self
-                    .rooms
-                    .get(&room_id)
-                    .is_none_or(|state| state.generation() != generation);
-                if stale {
-                    return Ok(());
-                }
-                let Some(state) = self.rooms.remove(&room_id) else {
-                    return Ok(());
-                };
-                match state {
-                    RoomActorState::Opening {
-                        generation: current,
-                        sender,
-                    } if current == generation => {
-                        self.rooms
-                            .insert(room_id, RoomActorState::Open { generation, sender });
-                    }
-                    state => {
-                        self.rooms.insert(room_id, state);
-                    }
-                }
-            }
-            RoomActorEvent::Exited {
-                room_id,
-                generation,
-            } => {
-                if self
-                    .rooms
-                    .get(&room_id)
-                    .is_none_or(|state| state.generation() != generation)
-                {
-                    return Ok(());
-                }
-                let state = self
-                    .rooms
-                    .remove(&room_id)
-                    .expect("room generation was checked");
-                let pending = match state {
-                    RoomActorState::Closing { pending, .. } => pending,
-                    RoomActorState::Opening { .. } | RoomActorState::Open { .. } => VecDeque::new(),
-                };
-                for operation in pending {
-                    let (id, result) = match operation {
-                        DeferredRoomLifecycle::Open(id) => {
-                            (id, self.open_room(id, room_id.clone()).await)
-                        }
-                        DeferredRoomLifecycle::Close(id) => {
-                            (id, self.close_room(id, &room_id).await)
-                        }
-                    };
-                    match result {
-                        Ok(true) => {}
-                        Ok(false) => emit_command_result(
-                            &self.port.event_sender(),
-                            id,
-                            CommandKind::Room,
-                            Ok(()),
-                        )
-                        .await
-                        .map_err(|_| EngineError::EventReceiverClosed)?,
-                        Err(error) => emit_command_result(
-                            &self.port.event_sender(),
-                            id,
-                            CommandKind::Room,
-                            Err(error),
-                        )
-                        .await
-                        .map_err(|_| EngineError::EventReceiverClosed)?,
-                    }
-                }
-                self.update_room_subscriptions().await;
-            }
-        }
-        Ok(())
-    }
-
-    async fn update_room_subscriptions(&self) {
-        let room_ids = self
-            .rooms
-            .iter()
-            .filter(|(_, state)| !matches!(state, RoomActorState::Closing { .. }))
-            .map(|(room_id, _)| room_id.clone())
-            .collect::<Vec<_>>();
-        let room_refs = room_ids.iter().map(AsRef::as_ref).collect::<Vec<_>>();
-        self.sync
-            .room_list_service()
-            .subscribe_to_rooms(&room_refs)
-            .await;
-    }
-
-    fn spawn_media_fetch(&mut self, command_id: CommandId, media_id: MediaId, size: MediaSize) {
-        let client = self.client.clone();
-        let media = self.media.clone();
-        let events = self.port.event_sender();
-        let max_media_bytes = self.max_media_bytes;
-        let flights = self.media_flights.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id: command_id,
-                kind: CommandKind::Media,
-            },
-            async move {
-                let leader = {
-                    let mut flights = flights.lock().await;
-                    let waiters = flights.entry((media_id.clone(), size)).or_default();
-                    waiters.push(command_id);
-                    waiters.len() == 1
-                };
-                if !leader {
-                    return;
-                }
-                let result = fetch_media(
-                    client,
-                    media,
-                    events.clone(),
-                    max_media_bytes,
-                    media_id.clone(),
-                    size,
-                )
-                .await;
-                let waiters = {
-                    let mut flights = flights.lock().await;
-                    flights.remove(&(media_id, size)).unwrap_or_default()
-                };
-                let result = match result {
-                    Ok(()) => Ok(()),
-                    Err(error) => {
-                        let kind = error.kind;
-                        let message = error.to_string();
-                        Err((kind, message))
-                    }
-                };
-                for waiter in waiters {
-                    let waiter_result = match &result {
-                        Ok(()) => Ok(()),
-                        Err((kind, message)) => Err(CommandError::new(*kind, message.clone())),
-                    };
-                    if emit_command_result(&events, waiter, CommandKind::Media, waiter_result)
-                        .await
-                        .is_err()
-                    {
-                        tracing::debug!(?waiter, "media fetch result was not delivered");
-                    }
-                }
-            },
-        );
-    }
-
-    async fn spawn_media_upload(
-        &mut self,
-        command_id: CommandId,
-        upload: AttachmentUpload,
-    ) -> Result<(), CommandError> {
-        let room_id = upload.timeline_id.room_id().clone();
-        let room = self.client.get_room(&room_id).ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::RoomUnknown,
-                "room is not available in the local store",
-            )
-        })?;
-        if self
-            .upload_watchers
-            .get(&room_id)
-            .is_some_and(|(watcher, _)| watcher.is_finished())
-        {
-            self.upload_watchers.remove(&room_id);
-        }
-        let ready = if let Some((_, ready)) = self.upload_watchers.get(&room_id) {
-            ready.clone()
-        } else {
-            let (ready_sender, ready) = watch::channel(None);
-            let watched_room_id = room_id.clone();
-            let progress_room_id = room_id.clone();
-            let queued_room = room.clone();
-            let events = self.port.event_sender();
-            let watcher =
-                self.tasks
-                    .spawn(TaskContext::Watcher("media upload watcher"), async move {
-                        let (_, mut updates) = match queued_room.send_queue().subscribe().await {
-                            Ok(subscription) => subscription,
-                            Err(source) => {
-                                tracing::warn!(room_id = %progress_room_id, error = %source, "reading media send queue failed");
-                                ready_sender.send_replace(Some(Err(CommandErrorKind::Store)));
-                                return;
-                            }
-                        };
-                        ready_sender.send_replace(Some(Ok(())));
-                        loop {
-                            match updates.recv().await {
-                                Ok(RoomSendQueueUpdate::MediaUpload {
-                                    related_to,
-                                    file,
-                                    progress,
-                                    ..
-                                }) => {
-                                    if events
-                                        .send(Event::MediaUploadProgress {
-                                            room_id: progress_room_id.clone(),
-                                            transaction_id: related_to,
-                                            uploaded_bytes: progress.current as u64,
-                                            total_bytes: progress.total as u64,
-                                            complete: file.is_some()
-                                                && progress.current == progress.total,
-                                        })
-                                        .await
-                                        .is_err()
-                                    {
-                                        break;
-                                    }
-                                }
-                                Ok(RoomSendQueueUpdate::SendError {
-                                    transaction_id,
-                                    error,
-                                    is_recoverable,
-                                }) => {
-                                    let is_attachment = queued_room
-                                        .send_queue()
-                                        .subscribe()
-                                        .await
-                                        .is_ok_and(|(echoes, _)| {
-                                            echoes.iter().any(|echo| {
-                                                echo.transaction_id == transaction_id
-                                                    && is_attachment_echo(&echo.content)
-                                            })
-                                        });
-                                    if is_attachment
-                                        && events
-                                            .send(Event::MediaUploadFailed {
-                                                room_id: progress_room_id.clone(),
-                                                transaction_id,
-                                                kind: classify_sdk_error(&error),
-                                                recoverable: is_recoverable,
-                                            })
-                                            .await
-                                            .is_err()
-                                    {
-                                        break;
-                                    }
-                                }
-                                Ok(_)
-                                | Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => {}
-                                Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
-                            }
-                        }
-                    });
-            self.upload_watchers
-                .insert(watched_room_id, (watcher, ready.clone()));
-            ready
-        };
-        let max_media_bytes = self.max_media_bytes;
-        let events = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id: command_id,
-                kind: CommandKind::Media,
-            },
-            async move {
-                let mut ready = ready;
-                let result = async {
-                    loop {
-                        if let Some(result) = *ready.borrow_and_update() {
-                            result.map_err(|kind| {
-                                CommandError::new(kind, "reading media send queue failed")
-                            })?;
-                            break;
-                        }
-                        ready.changed().await.map_err(|_| {
-                            CommandError::new(
-                                CommandErrorKind::Store,
-                                "media send queue watcher stopped",
-                            )
-                        })?;
-                    }
-                    queue_media_upload(room, upload, max_media_bytes).await
-                }
-                .await;
-                if emit_command_result(&events, command_id, CommandKind::Media, result)
-                    .await
-                    .is_err()
-                {
-                    tracing::debug!(?command_id, "media upload result was not delivered");
-                }
-            },
-        );
-        Ok(())
-    }
-
-    async fn shutdown(&mut self) {
-        self.tasks.shutdown().await;
-        self.verification.lock().await.stop().await;
-        self.rooms.clear();
-        self.upload_watchers.clear();
-        let mut media = self.media.lock().await;
-        media.entries.clear();
-        media.order.clear();
-        drop(media);
-        self.sync.stop().await;
-        self.port
-            .connection_sender()
-            .send_replace(ConnectionState::Stopped);
-        let _ = self
-            .port
-            .send(Event::ConnectionChanged(ConnectionState::Stopped))
-            .await;
-    }
-}
-
-async fn mark_read(
-    client: &Client,
-    timeline_id: &TimelineId,
-    event_id: OwnedEventId,
-) -> Result<(), CommandError> {
-    let room = client
-        .get_room(timeline_id.room_id())
-        .ok_or_else(room_unknown)?;
-    let receipt_thread = match timeline_id {
-        TimelineId::Room(_) => ReceiptThread::Main,
-        TimelineId::Thread { root_event_id, .. } => ReceiptThread::Thread(root_event_id.clone()),
-    };
-    room.send_single_receipt(ReceiptType::Read, receipt_thread, event_id.clone())
-        .await
-        .map_err(|source| CommandError::from_sdk("sending read receipt failed", source))?;
-    if matches!(timeline_id, TimelineId::Room(_)) {
-        room.send_single_receipt(ReceiptType::FullyRead, ReceiptThread::Unthreaded, event_id)
-            .await
-            .map_err(|source| {
-                CommandError::from_sdk("sending fully read receipt failed", source)
-            })?;
-    }
-    Ok(())
-}
-
-async fn set_typing(client: &Client, room_id: &RoomId, typing: bool) -> Result<(), CommandError> {
-    let room = client.get_room(room_id).ok_or_else(room_unknown)?;
-    room.typing_notice(typing)
-        .await
-        .map_err(|source| CommandError::from_sdk("typing update failed", source))
-}
-
-fn is_attachment_echo(content: &LocalEchoContent) -> bool {
-    let LocalEchoContent::Event {
-        serialized_event, ..
-    } = content
-    else {
-        return false;
-    };
-    matches!(
-        serialized_event.deserialize(),
-        Ok(AnyMessageLikeEventContent::RoomMessage(content))
-            if matches!(
-                content.msgtype,
-                MessageType::Audio(_) | MessageType::File(_) | MessageType::Image(_) | MessageType::Video(_)
-            )
-    )
-}
-
-async fn send_handle(
-    client: &Client,
-    room_id: &RoomId,
-    transaction_id: &matrix_sdk::ruma::TransactionId,
-) -> Result<SendHandle, CommandError> {
-    let room = client.get_room(room_id).ok_or_else(room_unknown)?;
-    let (echoes, _) = room.send_queue().subscribe().await.map_err(|source| {
-        CommandError::with_source(CommandErrorKind::Store, "reading send queue failed", source)
-    })?;
-    echoes
-        .into_iter()
-        .find_map(|echo| {
-            if echo.transaction_id.as_str() != transaction_id.as_str() {
-                return None;
-            }
-            match echo.content {
-                LocalEchoContent::Event { send_handle, .. } => Some(send_handle),
-                _ => None,
-            }
-        })
-        .ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::Other,
-                "send is no longer pending or is not a message",
-            )
-        })
-}
-
-async fn cancel_send(
-    client: &Client,
-    room_id: &RoomId,
-    transaction_id: &matrix_sdk::ruma::TransactionId,
-) -> Result<(), CommandError> {
-    let handle = send_handle(client, room_id, transaction_id).await?;
-    match handle.abort().await {
-        Ok(true) => Ok(()),
-        Ok(false) => Err(CommandError::new(
-            CommandErrorKind::Other,
-            "send could not be cancelled because it has already been sent",
-        )),
-        Err(source) => Err(CommandError::with_source(
-            CommandErrorKind::Store,
-            "cancelling send failed",
-            source,
-        )),
-    }
-}
-
-async fn retry_send(
-    client: &Client,
-    room_id: &RoomId,
-    transaction_id: &matrix_sdk::ruma::TransactionId,
-) -> Result<(), CommandError> {
-    let handle = send_handle(client, room_id, transaction_id).await?;
-    handle.unwedge().await.map_err(|source| {
-        CommandError::with_source(CommandErrorKind::Store, "retrying send failed", source)
-    })?;
-    if let Some(room) = client.get_room(room_id) {
-        room.send_queue().set_enabled(true);
-    }
-    Ok(())
-}
-
-fn send_room_actor_request(
-    sender: &mpsc::Sender<RoomActorRequest>,
-    request: RoomActorRequest,
-) -> Result<(), CommandError> {
-    sender.try_send(request).map_err(|error| match error {
-        mpsc::error::TrySendError::Full(_) => {
-            CommandError::new(CommandErrorKind::RoomBusy, "room command queue is full")
-        }
-        mpsc::error::TrySendError::Closed(_) => {
-            CommandError::new(CommandErrorKind::RoomNotOpen, "room is not open")
-        }
-    })
-}
-
-fn domain_queue_error<T>(error: mpsc::error::TrySendError<T>, domain: &str) -> CommandError {
-    match error {
-        mpsc::error::TrySendError::Full(_) => CommandError::new(
-            CommandErrorKind::QueueFull,
-            format!("{domain} command queue is full"),
-        ),
-        mpsc::error::TrySendError::Closed(_) => CommandError::new(
-            CommandErrorKind::Other,
-            format!("{domain} command worker has stopped"),
-        ),
-    }
-}
-
-async fn run_room_command_worker(
-    client: Client,
-    events: EventSender,
-    mut commands: mpsc::Receiver<RoomJob>,
-    queue_limit: usize,
-) {
-    let mut queues = HashMap::<RoomMutationKey, VecDeque<RoomJob>>::new();
-    let mut running = HashSet::<RoomMutationKey>::new();
-    let mut tasks = JoinSet::<RoomJobCompletion>::new();
-    let mut receiving = true;
-    let mut queued = 0_usize;
-    while receiving || !tasks.is_empty() {
-        tokio::select! {
-            biased;
-            completed = tasks.join_next(), if !tasks.is_empty() => {
-                let completion = match completed {
-                    Some(Ok(completion)) => completion,
-                    Some(Err(error)) => panic!("room command task failed: {error}"),
-                    None => continue,
-                };
-                let key = completion.key.clone();
-                emit_room_job_result(&events, completion).await;
-                let next = queues.get_mut(&key).and_then(VecDeque::pop_front);
-                if next.is_some() {
-                    queued -= 1;
-                }
-                if queues.get(&key).is_some_and(VecDeque::is_empty) {
-                    queues.remove(&key);
-                }
-                if let Some(job) = next {
-                    spawn_room_job(&mut tasks, client.clone(), key, job);
-                } else {
-                    running.remove(&key);
-                }
-            }
-            job = commands.recv(), if receiving => {
-                match job {
-                    Some(job) => {
-                        let key = room_mutation_key(job.id, &job.command);
-                        if running.insert(key.clone()) {
-                            spawn_room_job(&mut tasks, client.clone(), key, job);
-                        } else if queued < queue_limit {
-                            queues.entry(key).or_default().push_back(job);
-                            queued += 1;
-                        } else {
-                            let failure = CommandFailure {
-                                id: job.id,
-                                command: CommandKind::Room,
-                                kind: CommandErrorKind::QueueFull,
-                                message: "room command queue is full".to_owned(),
-                            };
-                            if let Some(reply) = job.reply {
-                                let _ = reply.send(Err(CommandResultError::Failed(failure)));
-                            } else {
-                                let _ = events.send(Event::CommandFailed(failure)).await;
-                            }
-                        }
-                    }
-                    None => receiving = false,
-                }
-            }
-        }
-    }
-}
-
-fn spawn_room_job(
-    tasks: &mut JoinSet<RoomJobCompletion>,
-    client: Client,
-    key: RoomMutationKey,
-    job: RoomJob,
-) {
-    tasks.spawn(async move {
-        let RoomJob { id, command, reply } = job;
-        let result = AssertUnwindSafe(execute_room_command(&client, command))
-            .catch_unwind()
-            .await
-            .unwrap_or_else(|_| {
-                Err(CommandError::new(
-                    CommandErrorKind::Other,
-                    "room command panicked",
-                ))
-            });
-        RoomJobCompletion {
-            key,
-            id,
-            reply,
-            result,
-        }
-    });
-}
-
-fn room_mutation_key(id: CommandId, command: &RoomCommand) -> RoomMutationKey {
-    match command {
-        RoomCommand::Join { room, .. } if room.is_room_id() => RoomMutationKey::Room(
-            OwnedRoomId::try_from(room.clone()).expect("room ID variant was checked"),
-        ),
-        RoomCommand::Join { room, .. } => RoomMutationKey::Target(room.to_string()),
-        RoomCommand::Leave(room_id)
-        | RoomCommand::Forget(room_id)
-        | RoomCommand::AcceptInvite(room_id)
-        | RoomCommand::RejectInvite(room_id)
-        | RoomCommand::InviteUser { room_id, .. }
-        | RoomCommand::KickUser { room_id, .. }
-        | RoomCommand::BanUser { room_id, .. }
-        | RoomCommand::UnbanUser { room_id, .. }
-        | RoomCommand::SetPowerLevels { room_id, .. }
-        | RoomCommand::SetUserPowerLevel { room_id, .. } => RoomMutationKey::Room(room_id.clone()),
-        RoomCommand::CreateDirect(user_id) => RoomMutationKey::Direct(user_id.clone()),
-        _ => RoomMutationKey::Independent(id),
-    }
-}
-
-async fn emit_room_job_result(events: &EventSender, completion: RoomJobCompletion) {
-    let RoomJobCompletion {
-        id, reply, result, ..
-    } = completion;
-    match result {
-        Ok(Some(room_id)) => {
-            if let Some(reply) = reply {
-                let _ = reply.send(Ok(room_id.clone()));
-            } else {
-                let _ = emit_command_result_with_room(events, id, room_id).await;
-            }
-        }
-        Ok(None) => {
-            if let Some(reply) = reply {
-                let _ = reply.send(Err(CommandResultError::Failed(CommandFailure {
-                    id,
-                    command: CommandKind::Room,
-                    kind: CommandErrorKind::Other,
-                    message: "room operation did not return a room ID".to_owned(),
-                })));
-            } else {
-                let _ = emit_command_result(events, id, CommandKind::Room, Ok(())).await;
-            }
-        }
-        Err(error) => {
-            let failure = CommandFailure {
-                id,
-                command: CommandKind::Room,
-                kind: error.kind,
-                message: error.to_string(),
-            };
-            if let Some(reply) = reply {
-                let _ = reply.send(Err(CommandResultError::Failed(failure)));
-            } else {
-                let _ = events.send(Event::CommandFailed(failure)).await;
-            }
-        }
-    }
-}
-
-async fn execute_room_command(
-    client: &Client,
-    command: RoomCommand,
-) -> Result<Option<OwnedRoomId>, CommandError> {
-    match command {
-        RoomCommand::Join { room, via } => client
-            .join_room_by_id_or_alias(&room, &via)
-            .await
-            .map(|room| Some(room.room_id().to_owned()))
-            .map_err(|source| CommandError::from_sdk("joining room failed", source)),
-        RoomCommand::Leave(room_id) => match client.get_room(&room_id) {
-            Some(room) => room
-                .leave()
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("leaving room failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::Forget(room_id) => match client.get_room(&room_id) {
-            Some(room) => room
-                .forget()
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("forgetting room failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::AcceptInvite(room_id) => match client.get_room(&room_id) {
-            Some(room) => room
-                .join()
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("accepting invite failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::RejectInvite(room_id) => match client.get_room(&room_id) {
-            Some(room) => room
-                .leave()
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("rejecting invite failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::InviteUser { room_id, user_id } => match client.get_room(&room_id) {
-            Some(room) => room
-                .invite_user_by_id(&user_id)
-                .await
-                .map(|()| None)
-                .map_err(|source| CommandError::from_sdk("inviting user failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::KickUser {
-            room_id,
-            user_id,
-            reason,
-        } => match client.get_room(&room_id) {
-            Some(room) => room
-                .kick_user(&user_id, reason.as_deref())
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("kicking user failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::BanUser {
-            room_id,
-            user_id,
-            reason,
-        } => match client.get_room(&room_id) {
-            Some(room) => room
-                .ban_user(&user_id, reason.as_deref())
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("banning user failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::UnbanUser {
-            room_id,
-            user_id,
-            reason,
-        } => match client.get_room(&room_id) {
-            Some(room) => room
-                .unban_user(&user_id, reason.as_deref())
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("unbanning user failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::SetPowerLevels { room_id, changes } => match client.get_room(&room_id) {
-            Some(room) => apply_power_level_changes(&room, changes)
-                .await
-                .map(|_| None),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::SetUserPowerLevel {
-            room_id,
-            user_id,
-            level,
-        } => match client.get_room(&room_id) {
-            Some(room) => match matrix_sdk::ruma::Int::try_from(level) {
-                Ok(level) => room
-                    .update_power_levels(vec![(&user_id, level)])
-                    .await
-                    .map(|_| None)
-                    .map_err(|source| {
-                        CommandError::from_sdk("updating user power level failed", source)
-                    }),
-                Err(_) => Err(CommandError::new(
-                    CommandErrorKind::Other,
-                    "power level is outside the Matrix integer range",
-                )),
-            },
-            None => Err(room_unknown()),
-        },
-        RoomCommand::Create(options) => client
-            .create_room(create_room_request(options))
-            .await
-            .map(|room| Some(room.room_id().to_owned()))
-            .map_err(|source| CommandError::from_sdk("creating room failed", source)),
-        RoomCommand::CreateDirect(user_id) => match client.get_dm_room(&user_id) {
-            Some(room) => Ok(Some(room.room_id().to_owned())),
-            None => client
-                .create_dm(&user_id)
-                .await
-                .map(|room| Some(room.room_id().to_owned()))
-                .map_err(|source| CommandError::from_sdk("creating direct room failed", source)),
-        },
-        _ => Err(CommandError::new(
-            CommandErrorKind::Other,
-            "unsupported room command",
-        )),
-    }
-}
-
-fn room_unknown() -> CommandError {
-    CommandError::new(
-        CommandErrorKind::RoomUnknown,
-        "room is not available in the local store",
-    )
-}
-
-const fn sdk_notification_mode(
-    mode: RoomNotificationMode,
-) -> matrix_sdk::notification_settings::RoomNotificationMode {
-    match mode {
-        RoomNotificationMode::AllMessages => {
-            matrix_sdk::notification_settings::RoomNotificationMode::AllMessages
-        }
-        RoomNotificationMode::MentionsAndKeywordsOnly => {
-            matrix_sdk::notification_settings::RoomNotificationMode::MentionsAndKeywordsOnly
-        }
-        RoomNotificationMode::Mute => matrix_sdk::notification_settings::RoomNotificationMode::Mute,
-    }
-}
-
-async fn execute_notification_command(
-    client: &Client,
-    command: NotificationCommand,
-) -> Result<(), CommandError> {
-    use matrix_sdk::notification_settings::{IsEncrypted, IsOneToOne};
-
-    let settings = client.notification_settings().await;
-    let result = match command {
-        NotificationCommand::SetRoomMode { room_id, mode } => {
-            settings
-                .set_room_notification_mode(&room_id, sdk_notification_mode(mode))
-                .await
-        }
-        NotificationCommand::ResetRoomMode(room_id) => {
-            settings.delete_user_defined_room_rules(&room_id).await
-        }
-        NotificationCommand::SetDefaultMode {
-            encrypted,
-            one_to_one,
-            mode,
-        } => {
-            settings
-                .set_default_room_notification_mode(
-                    IsEncrypted::from(encrypted),
-                    IsOneToOne::from(one_to_one),
-                    sdk_notification_mode(mode),
-                )
-                .await
-        }
-        NotificationCommand::AddKeyword(keyword) => settings.add_keyword(keyword).await,
-        NotificationCommand::RemoveKeyword(keyword) => settings.remove_keyword(&keyword).await,
-    };
-    result.map_err(|source| {
-        CommandError::with_source(
-            CommandErrorKind::Server,
-            "updating notification settings failed",
-            source,
-        )
-    })
-}
-
-async fn execute_encryption_command(
-    client: &Client,
-    events: &EventSender,
-    verification: &mut VerificationController,
-    command: EncryptionCommand,
-) -> Result<(), CommandError> {
-    match command {
-        EncryptionCommand::Recover(key) => client
-            .encryption()
-            .recovery()
-            .recover(&key)
-            .await
-            .map_err(|source| CommandError::from_recovery("account recovery failed", source)),
-        EncryptionCommand::StartVerification(target) => {
-            verification.start(client, events.clone(), target).await
-        }
-        EncryptionCommand::Verify(action) => {
-            verification.apply(client, events.clone(), action).await
-        }
-        command => execute_key_backup_command(client, command).await,
-    }
-}
-
-async fn execute_key_backup_command(
-    client: &Client,
-    command: EncryptionCommand,
-) -> Result<(), CommandError> {
-    match command {
-        EncryptionCommand::CreateKeyBackup => client
-            .encryption()
-            .backups()
-            .create()
-            .await
-            .map_err(|source| CommandError::from_sdk("creating key backup failed", source)),
-        EncryptionCommand::EnableKeyBackup => client
-            .encryption()
-            .recovery()
-            .enable_backup()
-            .await
-            .map_err(|source| CommandError::from_recovery("enabling key backup failed", source)),
-        EncryptionCommand::DisableKeyBackup { delete_from_server } => {
-            let backups = client.encryption().backups();
-            if delete_from_server {
-                backups.disable_and_delete().await
-            } else {
-                backups.disable().await
-            }
-            .map_err(|source| CommandError::from_sdk("disabling key backup failed", source))
-        }
-        EncryptionCommand::RecoverKeyBackup(key) => client
-            .encryption()
-            .recovery()
-            .recover_and_fix_backup(&key)
-            .await
-            .map_err(|source| CommandError::from_recovery("recovering key backup failed", source)),
-        _ => unreachable!("only key backup commands are spawned here"),
-    }
-}
-
-async fn apply_power_level_changes(
-    room: &Room,
-    changes: PowerLevelChanges,
-) -> Result<(), CommandError> {
-    use matrix_sdk::ruma::events::{
-        MessageLikeEventType, StateEventType, room::power_levels::RoomPowerLevelsEventContent,
-    };
-
-    let mut levels = room
-        .power_levels()
-        .await
-        .map_err(|source| CommandError::from_sdk("reading power levels failed", source.into()))?;
-    if let Some(value) = changes.ban {
-        levels.ban = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.invite {
-        levels.invite = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.kick {
-        levels.kick = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.redact {
-        levels.redact = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.events_default {
-        levels.events_default = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.state_default {
-        levels.state_default = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.users_default {
-        levels.users_default = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.room_notification {
-        levels.notifications.room = matrix_power_level(value)?;
-    }
-    for (event_type, value) in [
-        (StateEventType::RoomName.into(), changes.room_name),
-        (StateEventType::RoomAvatar.into(), changes.room_avatar),
-        (StateEventType::RoomTopic.into(), changes.room_topic),
-        (StateEventType::SpaceChild.into(), changes.space_child),
-        (MessageLikeEventType::Beacon.into(), changes.beacon),
-        (StateEventType::BeaconInfo.into(), changes.beacon_info),
-    ] {
-        if let Some(value) = value {
-            levels.events.insert(event_type, matrix_power_level(value)?);
-        }
-    }
-    let content = RoomPowerLevelsEventContent::try_from(levels).map_err(|source| {
-        CommandError::with_source(
-            CommandErrorKind::Other,
-            "normalizing power levels failed",
-            source,
-        )
-    })?;
-    room.send_state_event(content)
-        .await
-        .map(|_| ())
-        .map_err(|source| CommandError::from_sdk("updating power levels failed", source))
-}
-
-fn matrix_power_level(value: i64) -> Result<matrix_sdk::ruma::Int, CommandError> {
-    value.try_into().map_err(|source| {
-        CommandError::with_source(
-            CommandErrorKind::Other,
-            "power level is outside the Matrix integer range",
-            source,
-        )
-    })
-}
-
-fn create_room_request(
-    options: CreateRoomOptions,
-) -> matrix_sdk::ruma::api::client::room::create_room::v3::Request {
-    use matrix_sdk::ruma::api::client::room::{
-        Visibility as SdkVisibility,
-        create_room::v3::{Request, RoomPreset as SdkPreset},
-    };
-    let mut request = Request::new();
-    request.name = options.name;
-    request.topic = options.topic;
-    request.room_alias_name = options.alias_localpart;
-    request.invite = options.invite;
-    request.is_direct = options.direct;
-    request.visibility = match options.visibility {
-        RoomVisibility::Private => SdkVisibility::Private,
-        RoomVisibility::Public => SdkVisibility::Public,
-    };
-    request.preset = options.preset.map(|preset| match preset {
-        RoomPreset::PrivateChat => SdkPreset::PrivateChat,
-        RoomPreset::TrustedPrivateChat => SdkPreset::TrustedPrivateChat,
-        RoomPreset::PublicChat => SdkPreset::PublicChat,
-    });
-    request
-}
-
-async fn queue_media_upload(
-    room: Room,
-    upload: AttachmentUpload,
-    max_media_bytes: usize,
-) -> Result<(), CommandError> {
-    let (upload, mime, mut config) = prepare_upload(upload, max_media_bytes)?;
-    if let TimelineId::Thread { root_event_id, .. } = &upload.timeline_id {
-        config.reply = Some(SdkReply {
-            event_id: root_event_id.clone(),
-            enforce_thread: EnforceThread::Threaded(ReplyWithinThread::No),
-            add_mentions: AddMentions::No,
-        });
-    }
-    room.send_queue()
-        .send_attachment(upload.filename, mime, upload.bytes, config)
-        .await
-        .map(|_| ())
-        .map_err(|source| {
-            CommandError::with_source(
-                CommandErrorKind::MediaUnavailable,
-                "media upload could not be queued",
-                source,
-            )
-        })
-}
-
-async fn fetch_media(
-    client: Client,
-    registry: Arc<Mutex<MediaRegistry>>,
-    events: EventSender,
-    max_media_bytes: usize,
-    media_id: MediaId,
-    size: MediaSize,
-) -> Result<(), CommandError> {
-    let media = registry
-        .lock()
-        .await
-        .get(&media_id)
-        .cloned()
-        .ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::MediaUnknown,
-                "media is not registered in a retained timeline",
-            )
-        })?;
-    let (source, format, mimetype, declared_size) = match size {
-        MediaSize::Full => (
-            media.full.source,
-            MediaFormat::File,
-            media.full.mimetype,
-            media.full.declared_size,
-        ),
-        MediaSize::Thumbnail => {
-            if let Some(thumbnail) = media.thumbnail {
-                (
-                    thumbnail.source,
-                    MediaFormat::File,
-                    thumbnail.mimetype,
-                    thumbnail.declared_size,
-                )
-            } else if matches!(
-                media.kind,
-                crate::MediaKind::Image | crate::MediaKind::Video
-            ) && matches!(
-                &media.full.source,
-                matrix_sdk::ruma::events::room::MediaSource::Plain(_)
-            ) {
-                (
-                    media.full.source,
-                    MediaFormat::Thumbnail(MediaThumbnailSettings::new(
-                        800_u32.into(),
-                        800_u32.into(),
-                    )),
-                    media.full.mimetype,
-                    None,
-                )
-            } else {
-                return Err(CommandError::new(
-                    CommandErrorKind::MediaUnavailable,
-                    "the requested media size is unavailable",
-                ));
-            }
-        }
-    };
-    if declared_size.is_some_and(|size| size > max_media_bytes as u64) {
-        return Err(CommandError::new(
-            CommandErrorKind::MediaTooLarge,
-            "media exceeds the configured byte limit",
-        ));
-    }
-    let request = MediaRequestParameters { source, format };
-    if let Some(cached) = cached_media(&client, &request).await? {
-        if cached.len() > max_media_bytes {
-            remove_oversize_media(&client, &request).await;
-            return Err(CommandError::new(
-                CommandErrorKind::MediaTooLarge,
-                "cached media exceeds the configured byte limit",
-            ));
-        }
-        events
-            .send(Event::MediaReady {
-                media_id,
-                size,
-                bytes: Arc::from(cached),
-                mimetype: mimetype.unwrap_or_else(|| "application/octet-stream".into()),
-            })
-            .await
-            .map_err(send_error)?;
-        return Ok(());
-    }
-    let bytes = download_bounded(&client, &request, max_media_bytes).await?;
-    // the sdk caches plaintext under the encrypted key, so we do too or nobody can read anything
-    let bytes = maybe_decrypt_media(bytes, &request, max_media_bytes)?;
-    cache_media(&client, &request, &bytes).await;
-    events
-        .send(Event::MediaReady {
-            media_id,
-            size,
-            bytes: Arc::from(bytes),
-            mimetype: mimetype.unwrap_or_else(|| "application/octet-stream".into()),
-        })
-        .await
-        .map_err(send_error)
-}
-async fn cached_media(
-    client: &Client,
-    request: &MediaRequestParameters,
-) -> Result<Option<Vec<u8>>, CommandError> {
-    client
-        .media_store()
-        .lock()
-        .await
-        .map_err(|source| {
-            CommandError::with_source(
-                CommandErrorKind::Store,
-                "reading media cache failed",
-                source,
-            )
-        })?
-        .get_media_content(request)
-        .await
-        .map_err(|source| {
-            CommandError::with_source(
-                CommandErrorKind::Store,
-                "reading media cache failed",
-                source,
-            )
-        })
-}
-
-async fn remove_oversize_media(client: &Client, request: &MediaRequestParameters) {
-    if let Ok(store) = client.media_store().lock().await {
-        let _ = store.remove_media_content(request).await;
-    }
-}
-
-async fn cache_media(client: &Client, request: &MediaRequestParameters, bytes: &[u8]) {
-    if let Ok(store) = client.media_store().lock().await {
-        let _ = store
-            .add_media_content(
-                request,
-                bytes.to_vec(),
-                matrix_sdk::media::store::IgnoreMediaRetentionPolicy::No,
-            )
-            .await;
-    }
-}
-
-fn maybe_decrypt_media(
-    bytes: Vec<u8>,
-    request: &MediaRequestParameters,
-    max_media_bytes: usize,
-) -> Result<Vec<u8>, CommandError> {
-    let matrix_sdk::ruma::events::room::MediaSource::Encrypted(file) = &request.source else {
-        return Ok(bytes);
-    };
-    let info: MediaEncryptionInfo = (**file).clone().into();
-    let mut cursor = std::io::Cursor::new(bytes);
-    let mut decryptor = AttachmentDecryptor::new(&mut cursor, info).map_err(|source| {
-        CommandError::with_source(
-            CommandErrorKind::MediaUnavailable,
-            "media decryption failed",
-            source,
-        )
-    })?;
-    let mut decrypted = Vec::new();
-    let mut chunk = [0_u8; 8192];
-    loop {
-        match decryptor.read(&mut chunk) {
-            Ok(0) => break,
-            Ok(read) => {
-                if read > max_media_bytes.saturating_sub(decrypted.len()) {
-                    return Err(CommandError::new(
-                        CommandErrorKind::MediaTooLarge,
-                        "decrypted media exceeds the configured byte limit",
-                    ));
-                }
-                decrypted.extend_from_slice(&chunk[..read]);
-            }
-            Err(source) => {
-                return Err(CommandError::with_source(
-                    CommandErrorKind::MediaUnavailable,
-                    "media decryption failed",
-                    source,
-                ));
-            }
-        }
-    }
-    Ok(decrypted)
-}
-
-async fn download_bounded(
-    client: &Client,
-    request: &MediaRequestParameters,
-    max_media_bytes: usize,
-) -> Result<Vec<u8>, CommandError> {
-    if is_local_media(&request.source) {
-        return Err(CommandError::new(
-            CommandErrorKind::MediaUnavailable,
-            "local media is not in the media cache",
-        ));
-    }
-    let mut refreshed = false;
-    let request = loop {
-        let http_request = media_http_request(client, request).await?;
-        let response = client
-            .http_client()
-            .execute(request_from_http(client, http_request)?)
-            .await
-            .map_err(|source| {
-                CommandError::with_source(
-                    CommandErrorKind::Network,
-                    "media download failed",
-                    source,
-                )
-            })?;
-        if response.status() != matrix_sdk::reqwest::StatusCode::UNAUTHORIZED {
-            break response;
-        }
-        if refreshed
-            || client
-                .session_tokens()
-                .is_none_or(|tokens| tokens.refresh_token.is_none())
-        {
-            return Err(CommandError::new(
-                CommandErrorKind::Unauthenticated,
-                "media download was not authorized",
-            ));
-        }
-        client.refresh_access_token().await.map_err(|source| {
-            CommandError::from_refresh_token("refreshing media access token failed", source)
-        })?;
-        refreshed = true;
-    };
-    let status = request.status();
-    if !status.is_success() {
-        return Err(CommandError::new(
-            CommandErrorKind::MediaUnavailable,
-            format!("media download failed with status {status}"),
-        ));
-    }
-    if request
-        .content_length()
-        .is_some_and(|length| length > max_media_bytes as u64)
-    {
-        return Err(CommandError::new(
-            CommandErrorKind::MediaTooLarge,
-            "media exceeds the configured byte limit",
-        ));
-    }
-    let mut stream = request.bytes_stream();
-    let mut bytes = Vec::new();
-    while let Some(chunk) = stream.next().await {
-        let chunk = chunk.map_err(|source| {
-            CommandError::with_source(CommandErrorKind::Network, "media download failed", source)
-        })?;
-        if chunk.len() > max_media_bytes.saturating_sub(bytes.len()) {
-            return Err(CommandError::new(
-                CommandErrorKind::MediaTooLarge,
-                "downloaded media exceeds the configured byte limit",
-            ));
-        }
-        bytes.extend_from_slice(&chunk);
-    }
-    Ok(bytes)
-}
-
-fn is_local_media(source: &matrix_sdk::ruma::events::room::MediaSource) -> bool {
-    let uri = match source {
-        matrix_sdk::ruma::events::room::MediaSource::Plain(uri) => uri,
-        matrix_sdk::ruma::events::room::MediaSource::Encrypted(file) => &file.url,
-    };
-    let Ok(server) = uri.server_name() else {
-        return false;
-    };
-    server.as_str() == "send-queue.localhost"
-}
-
-async fn media_http_request(
-    client: &Client,
-    request: &MediaRequestParameters,
-) -> Result<http::Request<Vec<u8>>, CommandError> {
-    use matrix_sdk::ruma::api::client::{authenticated_media, media};
-
-    let versions = client.supported_versions().await.map_err(|source| {
-        CommandError::with_source(
-            CommandErrorKind::Network,
-            "reading supported server versions failed",
-            source,
-        )
-    })?;
-    let use_auth =
-        authenticated_media::get_content::v1::Request::PATH_BUILDER.is_supported(&versions);
-    let base = client.homeserver().to_string();
-    let token = client.access_token();
-    let build = |request: http::Request<Vec<u8>>| -> Result<http::Request<Vec<u8>>, CommandError> {
-        let mut request = request;
-        if let Some(token) = token.as_deref() {
-            request.headers_mut().insert(
-                http::header::AUTHORIZATION,
-                format!("Bearer {token}").parse().map_err(|_| {
-                    CommandError::new(
-                        CommandErrorKind::Unauthenticated,
-                        "stored access token is invalid",
-                    )
-                })?,
-            );
-        }
-        Ok(request)
-    };
-    match &request.source {
-        matrix_sdk::ruma::events::room::MediaSource::Encrypted(file) => {
-            if use_auth {
-                let endpoint = authenticated_media::get_content::v1::Request::from_uri(&file.url)
-                    .map_err(|source| {
-                    CommandError::with_source(
-                        CommandErrorKind::Other,
-                        "media URI is invalid",
-                        source,
-                    )
-                })?;
-                endpoint
-                    .try_into_http_request::<Vec<u8>>(
-                        &base,
-                        SendAccessToken::IfRequired(token.as_deref().unwrap_or("")),
-                        Cow::Borrowed(&versions),
-                    )
-                    .map_err(|_| {
-                        CommandError::new(
-                            CommandErrorKind::Unauthenticated,
-                            "media request could not be authorized",
-                        )
-                    })
-                    .and_then(build)
-            } else {
-                #[allow(deprecated)]
-                let endpoint =
-                    media::get_content::v3::Request::from_url(&file.url).map_err(|source| {
-                        CommandError::with_source(
-                            CommandErrorKind::Other,
-                            "media URI is invalid",
-                            source,
-                        )
-                    })?;
-                endpoint
-                    .try_into_http_request::<Vec<u8>>(
-                        &base,
-                        SendAccessToken::None,
-                        Cow::Borrowed(&versions),
-                    )
-                    .map_err(|_| {
-                        CommandError::new(CommandErrorKind::Other, "media request is invalid")
-                    })
-                    .and_then(build)
-            }
-        }
-        matrix_sdk::ruma::events::room::MediaSource::Plain(uri) => {
-            if let MediaFormat::Thumbnail(settings) = &request.format {
-                if use_auth {
-                    let mut endpoint =
-                        authenticated_media::get_content_thumbnail::v1::Request::from_uri(
-                            uri,
-                            settings.width,
-                            settings.height,
-                        )
-                        .map_err(|source| {
-                            CommandError::with_source(
-                                CommandErrorKind::Other,
-                                "media URI is invalid",
-                                source,
-                            )
-                        })?;
-                    endpoint.method = Some(settings.method.clone());
-                    endpoint.animated = Some(settings.animated);
-                    endpoint
-                        .try_into_http_request::<Vec<u8>>(
-                            &base,
-                            SendAccessToken::IfRequired(token.as_deref().unwrap_or("")),
-                            Cow::Borrowed(&versions),
-                        )
-                        .map_err(|_| {
-                            CommandError::new(
-                                CommandErrorKind::Unauthenticated,
-                                "media request could not be authorized",
-                            )
-                        })
-                        .and_then(build)
-                } else {
-                    #[allow(deprecated)]
-                    let endpoint = {
-                        let mut endpoint = media::get_content_thumbnail::v3::Request::from_url(
-                            uri,
-                            settings.width,
-                            settings.height,
-                        )
-                        .map_err(|source| {
-                            CommandError::with_source(
-                                CommandErrorKind::Other,
-                                "media URI is invalid",
-                                source,
-                            )
-                        })?;
-                        endpoint.method = Some(settings.method.clone());
-                        endpoint.animated = Some(settings.animated);
-                        endpoint
-                    };
-                    endpoint
-                        .try_into_http_request::<Vec<u8>>(
-                            &base,
-                            SendAccessToken::None,
-                            Cow::Borrowed(&versions),
-                        )
-                        .map_err(|_| {
-                            CommandError::new(CommandErrorKind::Other, "media request is invalid")
-                        })
-                        .and_then(build)
-                }
-            } else if use_auth {
-                let endpoint = authenticated_media::get_content::v1::Request::from_uri(uri)
-                    .map_err(|source| {
-                        CommandError::with_source(
-                            CommandErrorKind::Other,
-                            "media URI is invalid",
-                            source,
-                        )
-                    })?;
-                endpoint
-                    .try_into_http_request::<Vec<u8>>(
-                        &base,
-                        SendAccessToken::IfRequired(token.as_deref().unwrap_or("")),
-                        Cow::Borrowed(&versions),
-                    )
-                    .map_err(|_| {
-                        CommandError::new(
-                            CommandErrorKind::Unauthenticated,
-                            "media request could not be authorized",
-                        )
-                    })
-                    .and_then(build)
-            } else {
-                #[allow(deprecated)]
-                let endpoint =
-                    media::get_content::v3::Request::from_url(uri).map_err(|source| {
-                        CommandError::with_source(
-                            CommandErrorKind::Other,
-                            "media URI is invalid",
-                            source,
-                        )
-                    })?;
-                endpoint
-                    .try_into_http_request::<Vec<u8>>(
-                        &base,
-                        SendAccessToken::None,
-                        Cow::Borrowed(&versions),
-                    )
-                    .map_err(|_| {
-                        CommandError::new(CommandErrorKind::Other, "media request is invalid")
-                    })
-                    .and_then(build)
-            }
-        }
-    }
-}
-
-fn request_from_http(
-    client: &Client,
-    request: http::Request<Vec<u8>>,
-) -> Result<matrix_sdk::reqwest::Request, CommandError> {
-    let (parts, _) = request.into_parts();
-    let mut builder = client.http_client().get(parts.uri.to_string());
-    for (name, value) in parts.headers.iter() {
-        builder = builder.header(name.as_str(), value.as_bytes());
-    }
-    builder
-        .build()
-        .map_err(|_| CommandError::new(CommandErrorKind::Network, "media request is invalid"))
-}
-
-impl RoomActor {
-    async fn finish(
-        &mut self,
-        id: CommandId,
-        outcome: TimelineOutcome,
-    ) -> Result<(), SendEventError> {
-        match outcome {
-            TimelineOutcome::Done(result) => {
-                emit_command_result(&self.events, id, CommandKind::Timeline, result).await
-            }
-            TimelineOutcome::Background(work) => {
-                let task = self.background.spawn(async move { (id, work.await) });
-                self.background_ids.insert(task.id(), id);
-                Ok(())
-            }
-        }
-    }
-
-    async fn reap(&mut self, completed: BackgroundResult) -> Result<(), SendEventError> {
-        let (id, result) = match completed {
-            Ok((task_id, completed)) => {
-                self.background_ids.remove(&task_id);
-                completed
-            }
-            Err(error) => {
-                let Some(id) = self.background_ids.remove(&error.id()) else {
-                    return Ok(());
-                };
-                (
-                    id,
-                    Err(CommandError::new(
-                        CommandErrorKind::Other,
-                        "timeline operation panicked",
-                    )),
-                )
-            }
-        };
-        emit_command_result(&self.events, id, CommandKind::Timeline, result).await
-    }
-
-    async fn run(mut self, current_user_id: Option<ruma::OwnedUserId>) {
-        let timeline = match self
-            .room
-            .timeline_builder()
-            .with_focus(TimelineFocus::Live {
-                hide_threaded_events: true,
-            })
-            .track_read_marker_and_receipts(TimelineReadReceiptTracking::AllEvents)
-            .build()
-            .await
-        {
-            Ok(timeline) => timeline,
-            Err(error) => {
-                tracing::warn!(error = %error, room_id = %self.room_id, "room actor could not build its timeline");
-                let message = format!("room timeline build failed: {error}");
-                for id in self.open_ids.drain(..) {
-                    let _ = emit_command_result(
-                        &self.events,
-                        id,
-                        CommandKind::Room,
-                        Err(CommandError::new(
-                            CommandErrorKind::Timeline,
-                            message.clone(),
-                        )),
-                    )
-                    .await;
-                }
-                self.receiver.close();
-                while let Some(request) = self.receiver.recv().await {
-                    let (id, command) = match request {
-                        RoomActorRequest::Opened { id } | RoomActorRequest::Close { id } => {
-                            (id, CommandKind::Room)
-                        }
-                        RoomActorRequest::Execute { id, .. } => (id, CommandKind::Timeline),
-                    };
-                    let _ = emit_command_result(
-                        &self.events,
-                        id,
-                        command,
-                        Err(CommandError::new(
-                            CommandErrorKind::Timeline,
-                            "room timeline build failed",
-                        )),
-                    )
-                    .await;
-                }
-                return;
-            }
-        };
-        let room_timeline_id = TimelineId::Room(self.room_id.clone());
-        let mut room_timeline = match TimelineSession::start(
-            room_timeline_id,
-            timeline,
-            self.events.clone(),
-            self.media.clone(),
-            current_user_id.clone(),
-            self.initial_history_limit,
-        )
-        .await
-        {
-            Ok(timeline) => timeline,
-            Err(_) => return,
-        };
-        let _ = self.engine_events.send(RoomActorEvent::Ready {
-            room_id: self.room_id.clone(),
-            generation: self.generation,
-        });
-        for id in self.open_ids.drain(..) {
-            if emit_command_result(&self.events, id, CommandKind::Room, Ok(()))
-                .await
-                .is_err()
-            {
-                return;
-            }
-        }
-
-        let (typing_guard, mut typing_rx) = self.room.subscribe_to_typing_notifications();
-        let typing_sender = self.events.clone();
-        let typing_room_id = self.room_id.clone();
-        let mut room_tasks = JoinSet::new();
-        room_tasks.spawn(async move {
-            loop {
-                match typing_rx.recv().await {
-                    Ok(users) => {
-                        let state = TypingState {
-                            room_id: typing_room_id.clone(),
-                            users,
-                        };
-                        if typing_sender
-                            .send(Event::TypingChanged(state))
-                            .await
-                            .is_err()
-                        {
-                            tracing::debug!(
-                                room_id = %typing_room_id,
-                                "typing watcher stopped because the event receiver closed"
-                            );
-                            break;
-                        }
-                    }
-                    Err(tokio::sync::broadcast::error::RecvError::Lagged(skipped)) => {
-                        tracing::warn!(room_id = %typing_room_id, skipped, "typing watcher lagged");
-                    }
-                    Err(tokio::sync::broadcast::error::RecvError::Closed) => {
-                        tracing::debug!(room_id = %typing_room_id, "typing watcher stopped");
-                        break;
-                    }
-                }
-            }
-        });
-
-        enum QueuedThreadCommand {
-            Open {
-                id: CommandId,
-            },
-            Execute {
-                id: CommandId,
-                command: TimelineCommand,
-            },
-        }
-
-        struct OpeningThread {
-            generation: u64,
-            abort: AbortHandle,
-            task_id: TaskId,
-            queued: VecDeque<QueuedThreadCommand>,
-        }
-
-        let mut thread_timelines = HashMap::<OwnedEventId, TimelineSession>::new();
-        let mut opening_threads = HashMap::<OwnedEventId, OpeningThread>::new();
-        let mut thread_task_ids = HashMap::<TaskId, OwnedEventId>::new();
-        let mut thread_open_tasks = JoinSet::new();
-        let mut next_thread_generation = 0_u64;
-        let mut close_id = None;
-        let thread_queue_cap = self.receiver.max_capacity();
-        let mut queued_thread_count = 0;
-
-        let mut room_info = self.room.subscribe_info();
-        'actor: loop {
-            tokio::select! {
-                Some(info) = room_info.next() => {
-                    if matches!(info.state(), matrix_sdk::RoomState::Left | matrix_sdk::RoomState::Banned) {
-                        tracing::debug!(room_id = %self.room_id, "room actor stopped because we left the room");
-                        break 'actor;
-                    }
-                }
-                request = self.receiver.recv() => {
-                    let Some(request) = request else {
-                        tracing::debug!(room_id = %self.room_id, "room actor stopped because its request channel closed");
-                        break;
-                    };
-                    match request {
-                        RoomActorRequest::Opened { id } => {
-                            if emit_command_result(
-                                &self.events,
-                                id,
-                                CommandKind::Room,
-                                Ok(()),
-                            )
-                            .await
-                            .is_err()
-                            {
-                                break;
-                            }
-                        }
-                        RoomActorRequest::Execute { id, command } => {
-                            match command {
-                                TimelineCommand::OpenThread { root_event_id, .. } => {
-                                    if thread_timelines.contains_key(&root_event_id) {
-                                        if emit_command_result(
-                                            &self.events,
-                                            id,
-                                            CommandKind::Timeline,
-                                            Ok(()),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    } else if let Some(opening) =
-                                        opening_threads.get_mut(&root_event_id)
-                                    {
-                                        if queued_thread_count >= thread_queue_cap {
-                                            if emit_command_result(
-                                                &self.events,
-                                                id,
-                                                CommandKind::Timeline,
-                                                Err(CommandError::new(
-                                                    CommandErrorKind::QueueFull,
-                                                    "thread command queue is full",
-                                                )),
-                                            )
-                                            .await
-                                            .is_err()
-                                            {
-                                                break 'actor;
-                                            }
-                                        } else {
-                                            opening
-                                                .queued
-                                                .push_back(QueuedThreadCommand::Open { id });
-                                            queued_thread_count += 1;
-                                        }
-                                    } else if queued_thread_count >= thread_queue_cap {
-                                        if emit_command_result(
-                                            &self.events,
-                                            id,
-                                            CommandKind::Timeline,
-                                            Err(CommandError::new(
-                                                CommandErrorKind::QueueFull,
-                                                "thread command queue is full",
-                                            )),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    } else {
-                                        let generation = next_thread_generation;
-                                        next_thread_generation =
-                                            next_thread_generation.wrapping_add(1);
-                                        let task_root = root_event_id.clone();
-                                        let room = self.room.clone();
-                                        let abort = thread_open_tasks.spawn(async move {
-                                            let result = room
-                                                .timeline_builder()
-                                                .with_focus(TimelineFocus::Thread {
-                                                    root_event_id: root_event_id.clone(),
-                                                })
-                                                .track_read_marker_and_receipts(
-                                                    TimelineReadReceiptTracking::AllEvents,
-                                                )
-                                                .build()
-                                                .await;
-                                            (root_event_id, generation, result)
-                                        });
-                                        let task_id = abort.id();
-                                        thread_task_ids.insert(task_id, task_root.clone());
-                                        opening_threads.insert(
-                                            task_root,
-                                            OpeningThread {
-                                                generation,
-                                                abort,
-                                                task_id,
-                                                queued: VecDeque::from([
-                                                    QueuedThreadCommand::Open { id },
-                                                ]),
-                                            },
-                                        );
-                                        queued_thread_count += 1;
-                                    }
-                                }
-                                TimelineCommand::CloseThread { root_event_id, .. } => {
-                                    if let Some(timeline) = thread_timelines.remove(&root_event_id) {
-                                        timeline
-                                            .close(
-                                                CommandErrorKind::TimelineNotOpen,
-                                                "thread closed while pagination was in progress",
-                                            )
-                                            .await;
-                                        if emit_command_result(
-                                            &self.events,
-                                            id,
-                                            CommandKind::Timeline,
-                                            Ok(()),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    } else if let Some(opening) =
-                                        opening_threads.remove(&root_event_id)
-                                    {
-                                        thread_task_ids.remove(&opening.task_id);
-                                        queued_thread_count -= opening.queued.len();
-                                        opening.abort.abort();
-                                        for queued in opening.queued {
-                                            let queued_id = match queued {
-                                                QueuedThreadCommand::Open { id } => id,
-                                                QueuedThreadCommand::Execute { id, .. } => id,
-                                            };
-                                            let _ = emit_command_result(
-                                                &self.events,
-                                                queued_id,
-                                                CommandKind::Timeline,
-                                                Err(CommandError::new(
-                                                    CommandErrorKind::TimelineNotOpen,
-                                                    "thread was closed before it finished opening",
-                                                )),
-                                            )
-                                            .await;
-                                        }
-                                        if emit_command_result(
-                                            &self.events,
-                                            id,
-                                            CommandKind::Timeline,
-                                            Ok(()),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    } else if emit_command_result(
-                                        &self.events,
-                                        id,
-                                        CommandKind::Timeline,
-                                        Err(CommandError::new(
-                                            CommandErrorKind::TimelineNotOpen,
-                                            "thread timeline is not open",
-                                        )),
-                                    )
-                                    .await
-                                    .is_err()
-                                    {
-                                        break 'actor;
-                                    }
-                                }
-                                TimelineCommand::Paginate { timeline_id, limit } => {
-                                    match timeline_id {
-                                        TimelineId::Room(_) => {
-                                            room_timeline.paginate(limit, Some(id)).await;
-                                        }
-                                        TimelineId::Thread { room_id, root_event_id } => {
-                                            if let Some(timeline) =
-                                                thread_timelines.get_mut(&root_event_id)
-                                            {
-                                                timeline.paginate(limit, Some(id)).await;
-                                            } else if let Some(opening) =
-                                                opening_threads.get_mut(&root_event_id)
-                                            {
-                                                if queued_thread_count >= thread_queue_cap {
-                                                    if emit_command_result(
-                                                        &self.events,
-                                                        id,
-                                                        CommandKind::Timeline,
-                                                        Err(CommandError::new(
-                                                            CommandErrorKind::QueueFull,
-                                                            "thread command queue is full",
-                                                        )),
-                                                    )
-                                                    .await
-                                                    .is_err()
-                                                    {
-                                                        break 'actor;
-                                                    }
-                                                } else {
-                                                    opening.queued.push_back(
-                                                        QueuedThreadCommand::Execute {
-                                                            id,
-                                                            command:
-                                                                TimelineCommand::Paginate {
-                                                                    timeline_id:
-                                                                        TimelineId::Thread {
-                                                                            room_id,
-                                                                            root_event_id,
-                                                                        },
-                                                                    limit,
-                                                                },
-                                                        },
-                                                    );
-                                                    queued_thread_count += 1;
-                                                }
-                                            } else if emit_command_result(
-                                                &self.events,
-                                                id,
-                                                CommandKind::Timeline,
-                                                Err(CommandError::new(
-                                                    CommandErrorKind::TimelineNotOpen,
-                                                    "timeline is not open",
-                                                )),
-                                            )
-                                            .await
-                                            .is_err()
-                                            {
-                                                break 'actor;
-                                            }
-                                        }
-                                    }
-                                }
-                                command => {
-                                    let thread_target = match command
-                                        .timeline_id()
-                                        .expect("non-lifecycle timeline command has a timeline id")
-                                    {
-                                        TimelineId::Room(_) => None,
-                                        TimelineId::Thread { root_event_id, .. } => {
-                                            Some(root_event_id.clone())
-                                        }
-                                    };
-                                    match thread_target {
-                                        None => {
-                                            let result = execute_timeline_command(
-                                                &mut room_timeline,
-                                                command,
-                                                None,
-                                            )
-                                            .await;
-                                            if self.finish(id, result)
-                                            .await
-                                            .is_err()
-                                            {
-                                                tracing::debug!(room_id = %self.room_id, "room actor stopped because the event receiver closed");
-                                                break;
-                                            }
-                                        }
-                                        Some(root_event_id) => {
-                                            if let Some(timeline) =
-                                                thread_timelines.get_mut(&root_event_id)
-                                            {
-                                                let thread_root =
-                                                    timeline.id.thread_root().cloned();
-                                                let result = execute_timeline_command(
-                                                    timeline,
-                                                    command,
-                                                    thread_root.as_ref(),
-                                                )
-                                                .await;
-                                                if self.finish(id, result)
-                                                .await
-                                                .is_err()
-                                                {
-                                                    tracing::debug!(room_id = %self.room_id, "room actor stopped because the event receiver closed");
-                                                    break;
-                                                }
-                                            } else if let Some(opening) =
-                                                opening_threads.get_mut(&root_event_id)
-                                            {
-                                                if queued_thread_count >= thread_queue_cap {
-                                                    if emit_command_result(
-                                                        &self.events,
-                                                        id,
-                                                        CommandKind::Timeline,
-                                                        Err(CommandError::new(
-                                                            CommandErrorKind::QueueFull,
-                                                            "thread command queue is full",
-                                                        )),
-                                                    )
-                                                    .await
-                                                    .is_err()
-                                                    {
-                                                        break 'actor;
-                                                    }
-                                                } else {
-                                                    opening.queued.push_back(
-                                                        QueuedThreadCommand::Execute { id, command },
-                                                    );
-                                                    queued_thread_count += 1;
-                                                }
-                                            } else if emit_command_result(
-                                                &self.events,
-                                                id,
-                                                CommandKind::Timeline,
-                                                Err(CommandError::new(
-                                                    CommandErrorKind::TimelineNotOpen,
-                                                    "timeline is not open",
-                                                )),
-                                            )
-                                            .await
-                                            .is_err()
-                                            {
-                                                tracing::debug!(room_id = %self.room_id, "room actor stopped because the event receiver closed");
-                                                break;
-                                            }
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                        RoomActorRequest::Close { id } => {
-                            close_id = Some(id);
-                            break 'actor;
-                        }
-                    }
-                }
-                completed = thread_open_tasks.join_next(), if !thread_open_tasks.is_empty() => {
-                    match completed {
-                        Some(Ok((root_event_id, generation, result))) => {
-                            if opening_threads
-                                .get(&root_event_id)
-                                .is_none_or(|opening| opening.generation != generation)
-                            {
-                                continue;
-                            }
-                            let opening = opening_threads
-                                .remove(&root_event_id)
-                                .expect("thread generation was checked");
-                            thread_task_ids.remove(&opening.task_id);
-                            queued_thread_count -= opening.queued.len();
-                            match result {
-                                Ok(timeline) => {
-                                    let timeline_id = TimelineId::thread(
-                                        self.room_id.clone(),
-                                        root_event_id.clone(),
-                                    );
-                                    match TimelineSession::start(
-                                        timeline_id,
-                                        timeline,
-                                        self.events.clone(),
-                                        self.media.clone(),
-                                        current_user_id.clone(),
-                                        self.initial_history_limit,
-                                    )
-                                    .await
-                                    {
-                                        Ok(session) => {
-                                            thread_timelines
-                                                .insert(root_event_id.clone(), session);
-                                            let timeline = thread_timelines
-                                                .get_mut(&root_event_id)
-                                                .expect("thread session was inserted");
-                                            for queued in opening.queued {
-                                                match queued {
-                                                    QueuedThreadCommand::Open { id } => {
-                                                        if emit_command_result(
-                                                            &self.events,
-                                                            id,
-                                                            CommandKind::Timeline,
-                                                            Ok(()),
-                                                        )
-                                                        .await
-                                                        .is_err()
-                                                        {
-                                                            break 'actor;
-                                                        }
-                                                    }
-                                                    QueuedThreadCommand::Execute {
-                                                        id,
-                                                        command,
-                                                    } => match command {
-                                                        TimelineCommand::Paginate {
-                                                            limit,
-                                                            ..
-                                                        } => {
-                                                            timeline
-                                                                .paginate(limit, Some(id))
-                                                                .await;
-                                                        }
-                                                        command => {
-                                                            let thread_root = timeline
-                                                                .id
-                                                                .thread_root()
-                                                                .cloned();
-                                                            let result =
-                                                                execute_timeline_command(
-                                                                    timeline,
-                                                                    command,
-                                                                    thread_root.as_ref(),
-                                                                )
-                                                                .await;
-                                                            if self.finish(id, result)
-                                                            .await
-                                                            .is_err()
-                                                            {
-                                                                break 'actor;
-                                                            }
-                                                        }
-                                                    },
-                                                }
-                                            }
-                                        }
-                                        Err(_) => break 'actor,
-                                    }
-                                }
-                                Err(error) => {
-                                    tracing::warn!(error = %error, room_id = %self.room_id, %root_event_id, "thread timeline build failed");
-                                    let message = format!("thread timeline build failed: {error}");
-                                    for queued in opening.queued {
-                                        let queued_id = match queued {
-                                            QueuedThreadCommand::Open { id } => id,
-                                            QueuedThreadCommand::Execute { id, .. } => id,
-                                        };
-                                        if emit_command_result(
-                                            &self.events,
-                                            queued_id,
-                                            CommandKind::Timeline,
-                                            Err(CommandError::new(
-                                                CommandErrorKind::Timeline,
-                                                message.clone(),
-                                            )),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                        Some(Err(error)) => {
-                            if let Some(root_event_id) = thread_task_ids.remove(&error.id()) {
-                                tracing::warn!(error = %error, room_id = %self.room_id, %root_event_id, "thread open task failed");
-                                if let Some(opening) = opening_threads.remove(&root_event_id) {
-                                    queued_thread_count -= opening.queued.len();
-                                    for queued in opening.queued {
-                                        let queued_id = match queued {
-                                            QueuedThreadCommand::Open { id } => id,
-                                            QueuedThreadCommand::Execute { id, .. } => id,
-                                        };
-                                        if emit_command_result(
-                                            &self.events,
-                                            queued_id,
-                                            CommandKind::Timeline,
-                                            Err(CommandError::new(
-                                                CommandErrorKind::Timeline,
-                                                "thread timeline build task failed",
-                                            )),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    }
-                                }
-                            } else {
-                                tracing::debug!(error = %error, room_id = %self.room_id, "thread open task was aborted");
-                            }
-                        }
-                        None => {}
-                    }
-                }
-                Some(completed) = self.background.join_next_with_id(), if !self.background.is_empty() => {
-                    if self.reap(completed).await.is_err() {
-                        break 'actor;
-                    }
-                }
-                completed = room_tasks.join_next(), if !room_tasks.is_empty() => {
-                    match completed {
-                        Some(Err(error)) => {
-                            tracing::warn!(error = %error, room_id = %self.room_id, "room actor task failed");
-                        }
-                        Some(Ok(())) => {
-                            tracing::warn!(room_id = %self.room_id, "room actor task stopped unexpectedly");
-                        }
-                        None => {}
-                    }
-                }
-            }
-        }
-
-        while let Some(completed) = self.background.join_next_with_id().await {
-            let _ = self.reap(completed).await;
-        }
-        drop(typing_guard);
-        room_tasks.abort_all();
-        while room_tasks.join_next().await.is_some() {}
-        thread_task_ids.clear();
-        let pending_opens = opening_threads
-            .drain()
-            .flat_map(|(_, opening)| opening.queued)
-            .collect::<Vec<_>>();
-        for queued in pending_opens {
-            let queued_id = match queued {
-                QueuedThreadCommand::Open { id } => id,
-                QueuedThreadCommand::Execute { id, .. } => id,
-            };
-            let _ = emit_command_result(
-                &self.events,
-                queued_id,
-                CommandKind::Timeline,
-                Err(CommandError::new(
-                    CommandErrorKind::RoomNotOpen,
-                    "room closed while thread timeline was opening",
-                )),
-            )
-            .await;
-        }
-        thread_open_tasks.abort_all();
-        while thread_open_tasks.join_next().await.is_some() {}
-        for (_, timeline) in thread_timelines {
-            timeline
-                .close(
-                    CommandErrorKind::RoomNotOpen,
-                    "room closed while thread pagination was in progress",
-                )
-                .await;
-        }
-        room_timeline
-            .close(
-                CommandErrorKind::RoomNotOpen,
-                "room closed while pagination was in progress",
-            )
-            .await;
-        if let Some(id) = close_id
-            && emit_command_result(&self.events, id, CommandKind::Room, Ok(()))
-                .await
-                .is_err()
-        {
-            tracing::debug!(room_id = %self.room_id, "room close acknowledgement was not delivered");
-        }
-    }
-}
-
-async fn execute_timeline_command(
-    session: &mut TimelineSession,
-    command: TimelineCommand,
-    thread_root: Option<&OwnedEventId>,
-) -> TimelineOutcome {
-    let timeline = session.timeline.clone();
-    let work: BackgroundWork = match command {
-        TimelineCommand::Redact {
-            event_id, reason, ..
-        } => Box::pin(async move {
-            timeline
-                .redact(&TimelineEventItemId::EventId(event_id), reason.as_deref())
-                .await
-                .map_err(timeline_error)
-        }),
-        TimelineCommand::ToggleReaction { event_id, key, .. } => Box::pin(async move {
-            timeline
-                .toggle_reaction(&TimelineEventItemId::EventId(event_id), &key)
-                .await
-                .map(|_| ())
-                .map_err(timeline_error)
-        }),
-        TimelineCommand::MarkRead { event_id, .. } => {
-            let thread = thread_root.is_some();
-            Box::pin(async move {
-                let receipt_failed =
-                    |source| CommandError::from_sdk("sending read receipt failed", source);
-                timeline
-                    .send_single_receipt(ReceiptType::Read, event_id.clone())
-                    .await
-                    .map_err(receipt_failed)?;
-                if !thread {
-                    timeline
-                        .send_single_receipt(ReceiptType::FullyRead, event_id)
-                        .await
-                        .map_err(receipt_failed)?;
-                }
-                Ok(())
-            })
-        }
-        command => {
-            return TimelineOutcome::Done(
-                execute_serial_timeline_command(session, command, thread_root).await,
-            );
-        }
-    };
-    TimelineOutcome::Background(work)
-}
-
-async fn execute_serial_timeline_command(
-    session: &mut TimelineSession,
-    command: TimelineCommand,
-    thread_root: Option<&OwnedEventId>,
-) -> Result<(), CommandError> {
-    let timeline = &session.timeline;
-    match command {
-        TimelineCommand::OpenThread { .. }
-        | TimelineCommand::CloseThread { .. }
-        | TimelineCommand::Redact { .. }
-        | TimelineCommand::ToggleReaction { .. }
-        | TimelineCommand::MarkRead { .. } => Err(CommandError::new(
-            CommandErrorKind::Other,
-            "timeline command was misrouted",
-        )),
-        TimelineCommand::Resync { .. } => session.resync().await.map_err(|_| {
-            CommandError::new(
-                CommandErrorKind::Timeline,
-                "timeline resync could not emit a reset",
-            )
-        }),
-        TimelineCommand::Paginate { .. } => Ok(()),
-        TimelineCommand::Send { content, .. } => {
-            let body = match &content {
-                MessageContent::Text { content, .. }
-                | MessageContent::Emote { content, .. }
-                | MessageContent::Reply { content, .. } => &content.body,
-            };
-            if body.trim().is_empty() {
-                return Err(CommandError::new(
-                    CommandErrorKind::EmptyBody,
-                    "message body is empty",
-                ));
-            }
-            match content {
-                MessageContent::Text { content, mentions } => timeline
-                    .send(
-                        message_content(content, mentions, false)
-                            .with_relation(None)
-                            .into(),
-                    )
-                    .await
-                    .map(|_| ())
-                    .map_err(timeline_error),
-                MessageContent::Emote { content, mentions } => timeline
-                    .send(
-                        message_content(content, mentions, true)
-                            .with_relation(None)
-                            .into(),
-                    )
-                    .await
-                    .map(|_| ())
-                    .map_err(timeline_error),
-                MessageContent::Reply {
-                    event_id,
-                    content,
-                    mentions,
-                    notify_replied_to,
-                } => {
-                    let content = timeline
-                        .room()
-                        .make_reply_event(
-                            message_content(content, mentions, false),
-                            SdkReply {
-                                event_id,
-                                enforce_thread: if thread_root.is_some() {
-                                    EnforceThread::Threaded(ReplyWithinThread::Yes)
-                                } else {
-                                    EnforceThread::MaybeThreaded
-                                },
-                                add_mentions: if notify_replied_to {
-                                    AddMentions::Yes
-                                } else {
-                                    AddMentions::No
-                                },
-                            },
-                        )
-                        .await
-                        .map_err(|source| {
-                            CommandError::with_source(
-                                CommandErrorKind::Timeline,
-                                "reply operation failed",
-                                source,
-                            )
-                        })?;
-                    if let Some(thread_root) = thread_root
-                        && !matches!(
-                            content.relates_to.as_ref(),
-                            Some(Relation::Thread(thread)) if &thread.event_id == thread_root
-                        )
-                    {
-                        return Err(CommandError::new(
-                            CommandErrorKind::Timeline,
-                            "reply target does not belong to the selected thread",
-                        ));
-                    }
-                    timeline
-                        .send(content.into())
-                        .await
-                        .map(|_| ())
-                        .map_err(timeline_error)
-                }
-            }
-        }
-        TimelineCommand::Edit {
-            event_id, content, ..
-        } => {
-            let (content, mentions, emote) = match content {
-                MessageEditContent::Text { content, mentions } => (content, mentions, false),
-                MessageEditContent::Emote { content, mentions } => (content, mentions, true),
-            };
-            if content.body.trim().is_empty() {
-                return Err(CommandError::new(
-                    CommandErrorKind::EmptyBody,
-                    "message body is empty",
-                ));
-            }
-            timeline
-                .edit(
-                    &TimelineEventItemId::EventId(event_id),
-                    EditedContent::RoomMessage(message_content(content, mentions, emote)),
-                )
-                .await
-                .map_err(timeline_error)
-        }
-    }
-}
-
-fn message_content(
-    content: RichText,
-    mentions: MessageMentions,
-    emote: bool,
-) -> RoomMessageEventContentWithoutRelation {
-    let content = match content.formatted_body {
-        Some(formatted_body) if emote => {
-            RoomMessageEventContentWithoutRelation::emote_html(content.body, formatted_body)
-        }
-        Some(formatted_body) => {
-            RoomMessageEventContentWithoutRelation::text_html(content.body, formatted_body)
-        }
-        None if emote => RoomMessageEventContentWithoutRelation::emote_plain(content.body),
-        None => RoomMessageEventContentWithoutRelation::text_plain(content.body),
-    };
-    let content = content.add_mentions(Mentions::with_user_ids(mentions.user_ids));
-    if mentions.room {
-        content.add_mentions(Mentions::with_room_mention())
-    } else {
-        content
-    }
-}
-
-async fn run_pagination(request: PaginationRequest) {
-    let PaginationRequest {
-        timeline,
-        events,
-        timeline_id,
-        limit,
-        command_id,
-        results,
-    } = request;
-    if events
-        .send(Event::HistoryChanged {
-            timeline_id: timeline_id.clone(),
-            state: HistoryState::Loading,
-        })
-        .await
-        .is_err()
-    {
-        if let Some(id) = command_id {
-            let _ = results.send((
-                id,
-                Err(CommandError::new(
-                    CommandErrorKind::EventReceiverClosed,
-                    "event receiver has closed",
-                )),
-            ));
-        }
-        return;
-    }
-    let result = timeline
-        .paginate_backwards(limit.max(1))
-        .await
-        .map_err(timeline_error);
-    match result {
-        Ok(at_start) => {
-            let _ = events
-                .send(Event::HistoryChanged {
-                    timeline_id,
-                    state: if at_start {
-                        HistoryState::StartReached
-                    } else {
-                        HistoryState::Idle
-                    },
-                })
-                .await;
-            if let Some(id) = command_id {
-                let _ = results.send((id, Ok(())));
-            }
-        }
-        Err(error) => {
-            let _ = events
-                .send(Event::HistoryChanged {
-                    timeline_id,
-                    state: HistoryState::Failed(error.to_string()),
-                })
-                .await;
-            if let Some(id) = command_id {
-                let _ = results.send((id, Err(error)));
-            }
-        }
-    }
-}
-
-async fn emit_command_result_with_room(
-    events: &EventSender,
-    id: CommandId,
-    room_id: OwnedRoomId,
-) -> Result<(), SendEventError> {
-    events
-        .send(Event::CommandSucceededWithRoom {
-            id,
-            command: CommandKind::Room,
-            room_id,
-        })
-        .await
-}
-
-async fn emit_command_result(
-    events: &EventSender,
-    id: CommandId,
-    command: CommandKind,
-    result: Result<(), CommandError>,
-) -> Result<(), SendEventError> {
-    let event = match result {
-        Ok(()) => Event::CommandSucceeded { id, command },
-        Err(error) => {
-            tracing::warn!(?id, ?command, error = ?error, "room actor command failed");
-            Event::CommandFailed(CommandFailure {
-                id,
-                command,
-                kind: error.kind,
-                message: error.to_string(),
-            })
-        }
-    };
-    events.send(event).await
-}
-
-fn send_error(source: SendEventError) -> CommandError {
-    CommandError::with_source(
-        CommandErrorKind::EventReceiverClosed,
-        "event receiver has closed",
-        source,
-    )
-}
-
-fn timeline_error(source: matrix_sdk_ui::timeline::Error) -> CommandError {
-    CommandError::with_source(
-        CommandErrorKind::Timeline,
-        "timeline operation failed",
-        source,
-    )
-}

Added file: src/engine/commands.rs+319 additions@@ -0,0 +1,319 @@
+use std::{future::Future, panic::AssertUnwindSafe};
+
+use futures_util::FutureExt;
+use matrix_sdk::{
+    Client,
+    notification_settings::{IsEncrypted, IsOneToOne, RoomNotificationMode as SdkMode},
+    ruma::{
+        OwnedDeviceId, OwnedEventId, RoomId, TransactionId,
+        api::client::receipt::create_receipt::v3::ReceiptType, events::receipt::ReceiptThread,
+    },
+    send_queue::{LocalEchoContent, SendHandle},
+};
+use tokio::sync::mpsc;
+
+use crate::{
+    EncryptionCommand, Error, ErrorKind, InteractiveAuth, InteractiveAuthChallenge,
+    NotificationCommand, RoomNotificationMode, TimelineId,
+    encryption::VerificationController,
+    transport::{EventSender, Responder},
+};
+
+pub(super) struct Job<T> {
+    pub(super) command: T,
+    pub(super) reply: Responder,
+}
+
+/// a panicking command answers with an error instead of taking its worker down with it
+pub(super) async fn guarded<T>(
+    label: &'static str,
+    work: impl Future<Output = Result<T, Error>>,
+) -> Result<T, Error> {
+    AssertUnwindSafe(work)
+        .catch_unwind()
+        .await
+        .unwrap_or_else(|_| Err(Error::new(ErrorKind::Other, format!("{label} panicked"))))
+}
+
+pub(super) async fn run_notifications(
+    client: Client,
+    mut jobs: mpsc::Receiver<Job<NotificationCommand>>,
+) {
+    while let Some(Job { command, reply }) = jobs.recv().await {
+        reply.done(guarded("notification command", notification(&client, command)).await);
+    }
+}
+
+pub(super) async fn run_encryption(
+    client: Client,
+    events: EventSender,
+    mut jobs: mpsc::Receiver<Job<EncryptionCommand>>,
+) {
+    let mut verification = VerificationController::default();
+    while let Some(Job { command, reply }) = jobs.recv().await {
+        let work = encryption(&client, &events, &mut verification, command);
+        reply.done(guarded("encryption command", work).await);
+    }
+}
+
+async fn encryption(
+    client: &Client,
+    events: &EventSender,
+    verification: &mut VerificationController,
+    command: EncryptionCommand,
+) -> Result<(), Error> {
+    let encryption = client.encryption();
+    match command {
+        EncryptionCommand::Recover(key) => encryption
+            .recovery()
+            .recover(&key)
+            .await
+            .map_err(|source| Error::from_recovery("account recovery failed", source)),
+        EncryptionCommand::RecoverKeyBackup(key) => encryption
+            .recovery()
+            .recover_and_fix_backup(&key)
+            .await
+            .map_err(|source| Error::from_recovery("recovering key backup failed", source)),
+        EncryptionCommand::CreateKeyBackup => encryption
+            .backups()
+            .create()
+            .await
+            .map_err(|source| Error::from_sdk("creating key backup failed", source)),
+        EncryptionCommand::EnableKeyBackup => encryption
+            .recovery()
+            .enable_backup()
+            .await
+            .map_err(|source| Error::from_recovery("enabling key backup failed", source)),
+        EncryptionCommand::DisableKeyBackup { delete_from_server } => {
+            let backups = encryption.backups();
+            if delete_from_server {
+                backups.disable_and_delete().await
+            } else {
+                backups.disable().await
+            }
+            .map_err(|source| Error::from_sdk("disabling key backup failed", source))
+        }
+        EncryptionCommand::StartVerification(target) => {
+            verification.start(client, events.clone(), target).await
+        }
+        EncryptionCommand::Verify(action) => verification.apply(events.clone(), action).await,
+    }
+}
+
+async fn notification(client: &Client, command: NotificationCommand) -> Result<(), Error> {
+    let settings = client.notification_settings().await;
+    match command {
+        NotificationCommand::SetRoomMode { room_id, mode } => {
+            settings
+                .set_room_notification_mode(&room_id, sdk_mode(mode))
+                .await
+        }
+        NotificationCommand::ResetRoomMode(room_id) => {
+            settings.delete_user_defined_room_rules(&room_id).await
+        }
+        NotificationCommand::SetDefaultMode {
+            encrypted,
+            one_to_one,
+            mode,
+        } => {
+            settings
+                .set_default_room_notification_mode(
+                    IsEncrypted::from(encrypted),
+                    IsOneToOne::from(one_to_one),
+                    sdk_mode(mode),
+                )
+                .await
+        }
+        NotificationCommand::AddKeyword(keyword) => settings.add_keyword(keyword).await,
+        NotificationCommand::RemoveKeyword(keyword) => settings.remove_keyword(&keyword).await,
+    }
+    .map_err(|source| {
+        Error::with_source(
+            ErrorKind::Server,
+            "updating notification settings failed",
+            source,
+        )
+    })
+}
+
+const fn sdk_mode(mode: RoomNotificationMode) -> SdkMode {
+    match mode {
+        RoomNotificationMode::AllMessages => SdkMode::AllMessages,
+        RoomNotificationMode::MentionsAndKeywordsOnly => SdkMode::MentionsAndKeywordsOnly,
+        RoomNotificationMode::Mute => SdkMode::Mute,
+    }
+}
+
+fn room(client: &Client, room_id: &RoomId) -> Result<matrix_sdk::Room, Error> {
+    client.get_room(room_id).ok_or_else(Error::room_unknown)
+}
+
+/// the closed-room path. without a timeline nothing stops the marker going backwards
+pub(super) async fn mark_read(
+    client: &Client,
+    timeline_id: &TimelineId,
+    event_id: OwnedEventId,
+) -> Result<(), Error> {
+    let room = room(client, timeline_id.room_id())?;
+    let receipt_failed = |source| Error::from_sdk("sending read receipt failed", source);
+    let thread = match timeline_id.thread_root() {
+        None => ReceiptThread::Main,
+        Some(root) => ReceiptThread::Thread(root.clone()),
+    };
+    room.send_single_receipt(ReceiptType::Read, thread, event_id.clone())
+        .await
+        .map_err(receipt_failed)?;
+    if timeline_id.thread_root().is_none() {
+        room.send_single_receipt(ReceiptType::FullyRead, ReceiptThread::Unthreaded, event_id)
+            .await
+            .map_err(receipt_failed)?;
+    }
+    Ok(())
+}
+
+pub(super) async fn set_typing(
+    client: &Client,
+    room_id: &RoomId,
+    typing: bool,
+) -> Result<(), Error> {
+    room(client, room_id)?
+        .typing_notice(typing)
+        .await
+        .map_err(|source| Error::from_sdk("typing update failed", source))
+}
+
+async fn send_handle(
+    client: &Client,
+    room_id: &RoomId,
+    transaction_id: &TransactionId,
+) -> Result<SendHandle, Error> {
+    let (echoes, _) = room(client, room_id)?
+        .send_queue()
+        .subscribe()
+        .await
+        .map_err(|source| {
+            Error::with_source(ErrorKind::Store, "reading send queue failed", source)
+        })?;
+    echoes
+        .into_iter()
+        .find_map(|echo| match echo.content {
+            LocalEchoContent::Event { send_handle, .. }
+                if echo.transaction_id.as_str() == transaction_id.as_str() =>
+            {
+                Some(send_handle)
+            }
+            _ => None,
+        })
+        .ok_or_else(|| {
+            Error::new(
+                ErrorKind::Invalid,
+                "send is no longer pending or is not a message",
+            )
+        })
+}
+
+pub(super) async fn cancel_send(
+    client: &Client,
+    room_id: &RoomId,
+    transaction_id: &TransactionId,
+) -> Result<(), Error> {
+    match send_handle(client, room_id, transaction_id)
+        .await?
+        .abort()
+        .await
+    {
+        Ok(true) => Ok(()),
+        Ok(false) => Err(Error::new(
+            ErrorKind::Invalid,
+            "send could not be cancelled because it has already been sent",
+        )),
+        Err(source) => Err(Error::with_source(
+            ErrorKind::Store,
+            "cancelling send failed",
+            source,
+        )),
+    }
+}
+
+pub(super) async fn retry_send(
+    client: &Client,
+    room_id: &RoomId,
+    transaction_id: &TransactionId,
+) -> Result<(), Error> {
+    send_handle(client, room_id, transaction_id)
+        .await?
+        .unwedge()
+        .await
+        .map_err(|source| Error::with_source(ErrorKind::Store, "retrying send failed", source))?;
+    room(client, room_id)?.send_queue().set_enabled(true);
+    Ok(())
+}
+
+pub(super) async fn upload_avatar(
+    client: &Client,
+    mimetype: &str,
+    bytes: Vec<u8>,
+    max_bytes: usize,
+) -> Result<(), Error> {
+    if bytes.len() > max_bytes {
+        return Err(Error::new(
+            ErrorKind::MediaTooLarge,
+            "avatar exceeds the configured byte limit",
+        ));
+    }
+    let mimetype: mime::Mime = mimetype
+        .parse()
+        .map_err(|_| Error::new(ErrorKind::Invalid, "avatar MIME type is invalid"))?;
+    if mimetype.type_() != mime::IMAGE {
+        return Err(Error::new(
+            ErrorKind::Invalid,
+            "an avatar has to be an image",
+        ));
+    }
+    client
+        .account()
+        .upload_avatar(&mimetype, bytes)
+        .await
+        .map(drop)
+        .map_err(|source| Error::from_sdk("uploading avatar failed", source))
+}
+
+pub(super) async fn rename_device(
+    client: &Client,
+    device_id: &OwnedDeviceId,
+    display_name: &str,
+) -> Result<(), Error> {
+    client
+        .rename_device(device_id, display_name)
+        .await
+        .map(drop)
+        .map_err(|source| Error::from_http("renaming device failed", source))
+}
+
+pub(super) async fn delete_devices(
+    client: &Client,
+    device_ids: &[OwnedDeviceId],
+    auth: Option<InteractiveAuth>,
+) -> Result<(), Error> {
+    let user_id = client
+        .user_id()
+        .ok_or_else(|| Error::new(ErrorKind::Unauthenticated, "the client is not logged in"))?;
+    let auth = auth
+        .map(|auth| auth.into_sdk(user_id))
+        .transpose()
+        .map_err(|message| {
+            Error::new(
+                ErrorKind::Invalid,
+                format!("interactive authentication data is invalid, {message}"),
+            )
+        })?;
+    match client.delete_devices(device_ids, auth).await {
+        Ok(_) => Ok(()),
+        Err(source) => match source.as_uiaa_response() {
+            Some(info) => Err(Error::interactive_auth(InteractiveAuthChallenge::from(
+                info,
+            ))),
+            None => Err(Error::from_http("deleting devices failed", source)),
+        },
+    }
+}

Added file: src/engine/media.rs+572 additions@@ -0,0 +1,572 @@
+use std::{
+    borrow::Cow,
+    collections::{HashMap, VecDeque},
+    io::Read as _,
+    panic::AssertUnwindSafe,
+    sync::Arc,
+};
+
+use futures_util::{
+    FutureExt, StreamExt,
+    future::{BoxFuture, Shared, WeakShared},
+};
+use matrix_sdk::{
+    Client, Room,
+    media::{MediaFormat, MediaRequestParameters, MediaThumbnailSettings},
+    room::reply::{EnforceThread, Reply as SdkReply},
+    ruma::{
+        api::{
+            Metadata, OutgoingRequest,
+            auth_scheme::SendAccessToken,
+            client::{authenticated_media, media},
+        },
+        events::room::{
+            MediaSource,
+            message::{AddMentions, ReplyWithinThread},
+        },
+    },
+};
+use matrix_sdk_crypto::{AttachmentDecryptor, MediaEncryptionInfo};
+use ruma::MxcUri;
+use tokio::sync::Mutex;
+
+use crate::{
+    AttachmentUpload, Error, ErrorKind, Media, MediaId, MediaKind, MediaSize, TimelineId,
+    normalise::{MediaRegistration, MediaScope},
+    upload::prepare_upload,
+};
+
+/// the uploader's thumbnail is used when there is one, this is only what we ask the server for
+const TIMELINE_THUMBNAIL: u32 = 800;
+
+type FlightFuture = BoxFuture<'static, Result<Media, Error>>;
+type Flight = Shared<FlightFuture>;
+
+/// owns everything needed to turn a media id or an mxc uri into bytes, so the
+/// handle can answer media queries without a trip through the engine
+pub(crate) struct MediaService {
+    client: Client,
+    registry: Mutex<MediaRegistry>,
+    flights: Mutex<HashMap<String, WeakShared<FlightFuture>>>,
+    max_bytes: usize,
+}
+
+impl MediaService {
+    pub(crate) fn new(client: Client, max_bytes: usize, max_sources: usize) -> Self {
+        Self {
+            client,
+            registry: Mutex::new(MediaRegistry::new(max_sources)),
+            flights: Mutex::new(HashMap::new()),
+            max_bytes,
+        }
+    }
+
+    pub(crate) async fn register(&self, media: Vec<MediaRegistration>) {
+        if !media.is_empty() {
+            self.registry.lock().await.insert_all(media);
+        }
+    }
+
+    pub(crate) async fn release(&self, scope: &MediaScope) {
+        self.registry.lock().await.release(scope);
+    }
+
+    pub(crate) async fn clear(&self) {
+        self.registry.lock().await.clear();
+    }
+
+    pub(crate) async fn timeline_media(
+        &self,
+        media_id: &MediaId,
+        size: MediaSize,
+    ) -> Result<Media, Error> {
+        let media = self
+            .registry
+            .lock()
+            .await
+            .get(media_id)
+            .cloned()
+            .ok_or_else(|| {
+                Error::new(
+                    ErrorKind::MediaUnknown,
+                    "media is not registered in a retained timeline",
+                )
+            })?;
+        let (source, format, mimetype, declared_size) = match size {
+            MediaSize::Full => (
+                media.full.source,
+                MediaFormat::File,
+                media.full.mimetype,
+                media.full.declared_size,
+            ),
+            MediaSize::Thumbnail { .. } => match media.thumbnail {
+                Some(thumbnail) => (
+                    thumbnail.source,
+                    MediaFormat::File,
+                    thumbnail.mimetype,
+                    thumbnail.declared_size,
+                ),
+                // the server can only resize what it can read
+                None if matches!(media.kind, MediaKind::Image | MediaKind::Video)
+                    && matches!(media.full.source, MediaSource::Plain(_)) =>
+                {
+                    (
+                        media.full.source,
+                        thumbnail_format(TIMELINE_THUMBNAIL, TIMELINE_THUMBNAIL),
+                        media.full.mimetype,
+                        None,
+                    )
+                }
+                None => {
+                    return Err(Error::new(
+                        ErrorKind::MediaUnavailable,
+                        "the requested media size is unavailable",
+                    ));
+                }
+            },
+        };
+        if declared_size.is_some_and(|size| size > self.max_bytes as u64) {
+            return Err(too_large("media exceeds the configured byte limit"));
+        }
+        self.fetch(MediaRequestParameters { source, format }, mimetype)
+            .await
+    }
+
+    pub(crate) async fn mxc_media(&self, uri: &MxcUri, size: MediaSize) -> Result<Media, Error> {
+        if !uri.is_valid() {
+            return Err(Error::new(ErrorKind::Invalid, "mxc uri is malformed"));
+        }
+        let format = match size {
+            MediaSize::Full => MediaFormat::File,
+            MediaSize::Thumbnail { width, height } => thumbnail_format(width, height),
+        };
+        self.fetch(
+            MediaRequestParameters {
+                source: MediaSource::Plain(uri.to_owned()),
+                format,
+            },
+            None,
+        )
+        .await
+    }
+
+    async fn fetch(
+        &self,
+        request: MediaRequestParameters,
+        mimetype: Option<String>,
+    ) -> Result<Media, Error> {
+        let key = flight_key(&request);
+        let flight = {
+            let mut flights = self.flights.lock().await;
+            flights.retain(|_, flight| flight.upgrade().is_some());
+            match flights.get(&key).and_then(WeakShared::upgrade) {
+                Some(flight) => flight,
+                None => {
+                    let flight: Flight = AssertUnwindSafe(fetch(
+                        self.client.clone(),
+                        request,
+                        mimetype,
+                        self.max_bytes,
+                    ))
+                    .catch_unwind()
+                    .map(|result| {
+                        result.unwrap_or_else(|_| {
+                            Err(Error::new(ErrorKind::Other, "media fetch panicked"))
+                        })
+                    })
+                    .boxed()
+                    .shared();
+                    if let Some(weak) = flight.downgrade() {
+                        flights.insert(key, weak);
+                    }
+                    flight
+                }
+            }
+        };
+        flight.await
+    }
+}
+
+fn thumbnail_format(width: u32, height: u32) -> MediaFormat {
+    MediaFormat::Thumbnail(MediaThumbnailSettings::new(width.into(), height.into()))
+}
+
+fn flight_key(request: &MediaRequestParameters) -> String {
+    let uri = match &request.source {
+        MediaSource::Plain(uri) => uri.as_str(),
+        MediaSource::Encrypted(file) => file.url.as_str(),
+    };
+    match &request.format {
+        MediaFormat::File => uri.to_owned(),
+        MediaFormat::Thumbnail(settings) => format!(
+            "{uri}|{}|{}x{}|{}",
+            settings.method, settings.width, settings.height, settings.animated
+        ),
+    }
+}
+
+fn too_large(message: &'static str) -> Error {
+    Error::new(ErrorKind::MediaTooLarge, message)
+}
+
+async fn fetch(
+    client: Client,
+    request: MediaRequestParameters,
+    mimetype: Option<String>,
+    max_bytes: usize,
+) -> Result<Media, Error> {
+    if let Some(cached) = cached_media(&client, &request).await? {
+        if cached.len() > max_bytes {
+            if let Ok(store) = client.media_store().lock().await {
+                let _ = store.remove_media_content(&request).await;
+            }
+            return Err(too_large("cached media exceeds the configured byte limit"));
+        }
+        return Ok(media(cached, mimetype));
+    }
+    let (bytes, served_mimetype) = download_bounded(&client, &request, max_bytes).await?;
+    // the sdk caches plaintext under the encrypted key, so we do too or nobody can read anything
+    let bytes = maybe_decrypt(bytes, &request, max_bytes)?;
+    if let Ok(store) = client.media_store().lock().await {
+        let _ = store
+            .add_media_content(
+                &request,
+                bytes.clone(),
+                matrix_sdk::media::store::IgnoreMediaRetentionPolicy::No,
+            )
+            .await;
+    }
+    Ok(media(bytes, mimetype.or(served_mimetype)))
+}
+
+fn media(bytes: Vec<u8>, mimetype: Option<String>) -> Media {
+    let mimetype = mimetype
+        .or_else(|| sniff_image(&bytes).map(str::to_owned))
+        .unwrap_or_else(|| "application/octet-stream".to_owned());
+    Media {
+        bytes: Arc::from(bytes),
+        mimetype,
+    }
+}
+
+/// the cache forgets content types, and avatars never declare one. images are the common case
+fn sniff_image(bytes: &[u8]) -> Option<&'static str> {
+    match bytes {
+        [0x89, b'P', b'N', b'G', ..] => Some("image/png"),
+        [0xff, 0xd8, 0xff, ..] => Some("image/jpeg"),
+        [b'G', b'I', b'F', b'8', ..] => Some("image/gif"),
+        [
+            b'R',
+            b'I',
+            b'F',
+            b'F',
+            _,
+            _,
+            _,
+            _,
+            b'W',
+            b'E',
+            b'B',
+            b'P',
+            ..,
+        ] => Some("image/webp"),
+        _ => None,
+    }
+}
+
+async fn cached_media(
+    client: &Client,
+    request: &MediaRequestParameters,
+) -> Result<Option<Vec<u8>>, Error> {
+    fn cache_failed(source: impl std::error::Error + Send + Sync + 'static) -> Error {
+        Error::with_source(ErrorKind::Store, "reading media cache failed", source)
+    }
+    client
+        .media_store()
+        .lock()
+        .await
+        .map_err(cache_failed)?
+        .get_media_content(request)
+        .await
+        .map_err(cache_failed)
+}
+
+fn maybe_decrypt(
+    bytes: Vec<u8>,
+    request: &MediaRequestParameters,
+    max_bytes: usize,
+) -> Result<Vec<u8>, Error> {
+    let MediaSource::Encrypted(file) = &request.source else {
+        return Ok(bytes);
+    };
+    fn decrypt_failed(source: impl std::error::Error + Send + Sync + 'static) -> Error {
+        Error::with_source(
+            ErrorKind::MediaUnavailable,
+            "media decryption failed",
+            source,
+        )
+    }
+    let info: MediaEncryptionInfo = (**file).clone().into();
+    let mut cursor = std::io::Cursor::new(bytes);
+    let mut decryptor = AttachmentDecryptor::new(&mut cursor, info).map_err(decrypt_failed)?;
+    let mut decrypted = Vec::new();
+    let mut chunk = [0_u8; 8192];
+    loop {
+        let read = decryptor.read(&mut chunk).map_err(decrypt_failed)?;
+        if read == 0 {
+            return Ok(decrypted);
+        }
+        if read > max_bytes.saturating_sub(decrypted.len()) {
+            return Err(too_large(
+                "decrypted media exceeds the configured byte limit",
+            ));
+        }
+        decrypted.extend_from_slice(&chunk[..read]);
+    }
+}
+
+/// the sdk's own download has no size cap and no timeout, so we do it by hand
+async fn download_bounded(
+    client: &Client,
+    request: &MediaRequestParameters,
+    max_bytes: usize,
+) -> Result<(Vec<u8>, Option<String>), Error> {
+    let uri = match &request.source {
+        MediaSource::Plain(uri) => uri,
+        MediaSource::Encrypted(file) => &file.url,
+    };
+    if uri
+        .server_name()
+        .is_ok_and(|server| server.as_str() == "send-queue.localhost")
+    {
+        return Err(Error::new(
+            ErrorKind::MediaUnavailable,
+            "local media is not in the media cache",
+        ));
+    }
+    let network_failed =
+        |source| Error::with_source(ErrorKind::Network, "media download failed", source);
+    let mut refreshed = false;
+    let response = loop {
+        let http_request = media_http_request(client, request).await?;
+        let (parts, _) = http_request.into_parts();
+        let mut builder = client.http_client().get(parts.uri.to_string());
+        for (name, value) in &parts.headers {
+            builder = builder.header(name.as_str(), value.as_bytes());
+        }
+        let response = builder.send().await.map_err(network_failed)?;
+        if response.status() != matrix_sdk::reqwest::StatusCode::UNAUTHORIZED {
+            break response;
+        }
+        if refreshed
+            || client
+                .session_tokens()
+                .is_none_or(|tokens| tokens.refresh_token.is_none())
+        {
+            return Err(Error::new(
+                ErrorKind::Unauthenticated,
+                "media download was not authorized",
+            ));
+        }
+        client.refresh_access_token().await.map_err(|source| {
+            Error::from_refresh_token("refreshing media access token failed", source)
+        })?;
+        refreshed = true;
+    };
+    let status = response.status();
+    if !status.is_success() {
+        return Err(Error::new(
+            ErrorKind::MediaUnavailable,
+            format!("media download failed with status {status}"),
+        ));
+    }
+    if response
+        .content_length()
+        .is_some_and(|length| length > max_bytes as u64)
+    {
+        return Err(too_large("media exceeds the configured byte limit"));
+    }
+    let mimetype = response
+        .headers()
+        .get(http::header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .map(str::to_owned);
+    let mut stream = response.bytes_stream();
+    let mut bytes = Vec::new();
+    while let Some(chunk) = stream.next().await {
+        let chunk = chunk.map_err(network_failed)?;
+        if chunk.len() > max_bytes.saturating_sub(bytes.len()) {
+            return Err(too_large(
+                "downloaded media exceeds the configured byte limit",
+            ));
+        }
+        bytes.extend_from_slice(&chunk);
+    }
+    Ok((bytes, mimetype))
+}
+
+async fn media_http_request(
+    client: &Client,
+    request: &MediaRequestParameters,
+) -> Result<http::Request<Vec<u8>>, Error> {
+    let versions = client.supported_versions().await.map_err(|source| {
+        Error::with_source(
+            ErrorKind::Network,
+            "reading supported server versions failed",
+            source,
+        )
+    })?;
+    let authenticated =
+        authenticated_media::get_content::v1::Request::PATH_BUILDER.is_supported(&versions);
+    let base = client.homeserver().to_string();
+    let token = client.access_token();
+    let invalid_uri =
+        |source| Error::with_source(ErrorKind::Invalid, "media URI is invalid", source);
+    let (uri, thumbnail) = match (&request.source, &request.format) {
+        (MediaSource::Encrypted(file), _) => (&file.url, None),
+        (MediaSource::Plain(uri), MediaFormat::File) => (uri, None),
+        (MediaSource::Plain(uri), MediaFormat::Thumbnail(settings)) => (uri, Some(settings)),
+    };
+    // each endpoint has its own auth input type, so no generic helper can take them all
+    macro_rules! into_http {
+        ($endpoint:expr, $token:expr) => {
+            $endpoint
+                .try_into_http_request::<Vec<u8>>(&base, $token, Cow::Borrowed(&versions))
+                .map_err(|source| {
+                    Error::with_source(ErrorKind::Other, "media request is invalid", source)
+                })?
+        };
+    }
+    let authed = SendAccessToken::IfRequired(token.as_deref().unwrap_or(""));
+    #[allow(deprecated)]
+    let mut http_request = match (thumbnail, authenticated) {
+        (None, true) => into_http!(
+            authenticated_media::get_content::v1::Request::from_uri(uri).map_err(invalid_uri)?,
+            authed
+        ),
+        (None, false) => into_http!(
+            media::get_content::v3::Request::from_url(uri).map_err(invalid_uri)?,
+            SendAccessToken::None
+        ),
+        (Some(settings), true) => {
+            let mut endpoint = authenticated_media::get_content_thumbnail::v1::Request::from_uri(
+                uri,
+                settings.width,
+                settings.height,
+            )
+            .map_err(invalid_uri)?;
+            endpoint.method = Some(settings.method.clone());
+            endpoint.animated = Some(settings.animated);
+            into_http!(endpoint, authed)
+        }
+        (Some(settings), false) => {
+            let mut endpoint = media::get_content_thumbnail::v3::Request::from_url(
+                uri,
+                settings.width,
+                settings.height,
+            )
+            .map_err(invalid_uri)?;
+            endpoint.method = Some(settings.method.clone());
+            endpoint.animated = Some(settings.animated);
+            into_http!(endpoint, SendAccessToken::None)
+        }
+    };
+    // legacy endpoints don't ask for a token but plenty of servers want one anyway
+    if let Some(token) = token.as_deref() {
+        let value = format!("Bearer {token}").parse().map_err(|_| {
+            Error::new(ErrorKind::Unauthenticated, "stored access token is invalid")
+        })?;
+        http_request
+            .headers_mut()
+            .insert(http::header::AUTHORIZATION, value);
+    }
+    Ok(http_request)
+}
+
+pub(crate) async fn queue_upload(
+    room: Room,
+    upload: AttachmentUpload,
+    max_bytes: usize,
+) -> Result<(), Error> {
+    let (upload, mime, mut config) = prepare_upload(upload, max_bytes)?;
+    if let TimelineId::Thread { root_event_id, .. } = &upload.timeline_id {
+        config.reply = Some(SdkReply {
+            event_id: root_event_id.clone(),
+            enforce_thread: EnforceThread::Threaded(ReplyWithinThread::No),
+            add_mentions: AddMentions::No,
+        });
+    }
+    room.send_queue()
+        .send_attachment(upload.filename, mime, upload.bytes, config)
+        .await
+        .map(drop)
+        .map_err(|source| {
+            Error::with_source(
+                ErrorKind::MediaUnavailable,
+                "media upload could not be queued",
+                source,
+            )
+        })
+}
+
+/// least recently seen goes first. stale order slots are skipped by stamp rather than hunted down
+struct MediaRegistry {
+    entries: HashMap<MediaId, (MediaRegistration, u64)>,
+    order: VecDeque<(MediaId, u64)>,
+    next_stamp: u64,
+    limit: usize,
+}
+
+impl MediaRegistry {
+    fn new(limit: usize) -> Self {
+        Self {
+            entries: HashMap::new(),
+            order: VecDeque::new(),
+            next_stamp: 0,
+            limit,
+        }
+    }
+
+    fn get(&self, id: &MediaId) -> Option<&MediaRegistration> {
+        self.entries.get(id).map(|(media, _)| media)
+    }
+
+    fn insert_all(&mut self, media: Vec<MediaRegistration>) {
+        for media in media {
+            let stamp = self.next_stamp;
+            self.next_stamp += 1;
+            self.order.push_back((media.id.clone(), stamp));
+            self.entries.insert(media.id.clone(), (media, stamp));
+        }
+        while self.entries.len() > self.limit {
+            let Some((id, stamp)) = self.order.pop_front() else {
+                break;
+            };
+            if self.is_current(&id, stamp) {
+                self.entries.remove(&id);
+            }
+        }
+        if self.order.len() > self.limit.saturating_mul(4) {
+            let entries = &self.entries;
+            self.order
+                .retain(|(id, stamp)| entries.get(id).is_some_and(|(_, current)| current == stamp));
+        }
+    }
+
+    fn is_current(&self, id: &MediaId, stamp: u64) -> bool {
+        self.entries
+            .get(id)
+            .is_some_and(|(_, current)| *current == stamp)
+    }
+
+    fn release(&mut self, scope: &MediaScope) {
+        self.entries.retain(|id, _| !scope.owns(id));
+        let entries = &self.entries;
+        self.order.retain(|(id, _)| entries.contains_key(id));
+    }
+
+    fn clear(&mut self) {
+        self.entries.clear();
+        self.order.clear();
+    }
+}

Added file: src/engine/mod.rs+776 additions@@ -0,0 +1,776 @@
+mod commands;
+mod media;
+mod mutations;
+mod room;
+mod timeline;
+mod watchers;
+
+use std::{
+    collections::{HashMap, VecDeque},
+    future::Future,
+    sync::Arc,
+};
+
+use futures_util::future::BoxFuture;
+use matrix_sdk::{Client, SessionChange};
+use matrix_sdk_ui::sync_service::SyncService;
+use ruma::{OwnedRoomId, RoomId};
+use thiserror::Error as ThisError;
+use tokio::{
+    sync::{Notify, broadcast, mpsc, watch},
+    task::{AbortHandle, Id as TaskId, JoinError, JoinSet},
+};
+
+pub(crate) use media::MediaService;
+
+use self::{
+    commands::Job,
+    mutations::{Mutation, MutationJob},
+    room::{ActorRequest, Exited, RoomActor},
+    timeline::{SessionContext, Supervisor},
+};
+use crate::{
+    AccountCommand, ClientHandle, Command, ConnectionState, EncryptionCommand, EngineErrorKind,
+    EngineFailure, Error, ErrorKind, Event, EventStream, LifecycleCommand, MediaCommand,
+    NotificationCommand, RoomCommand, TimelineCommand,
+    transport::{DriverPort, Request, Responder, transport_pair},
+};
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub struct EngineConfig {
+    pub command_capacity: usize,
+    pub event_capacity: usize,
+    pub initial_history_limit: u16,
+    pub max_media_bytes: usize,
+    pub max_media_sources: usize,
+}
+
+impl EngineConfig {
+    #[must_use]
+    pub const fn with_command_capacity(mut self, capacity: usize) -> Self {
+        self.command_capacity = capacity;
+        self
+    }
+
+    #[must_use]
+    pub const fn with_event_capacity(mut self, capacity: usize) -> Self {
+        self.event_capacity = capacity;
+        self
+    }
+
+    #[must_use]
+    pub const fn with_initial_history_limit(mut self, limit: u16) -> Self {
+        self.initial_history_limit = limit;
+        self
+    }
+
+    #[must_use]
+    pub const fn with_max_media_bytes(mut self, bytes: usize) -> Self {
+        self.max_media_bytes = bytes;
+        self
+    }
+
+    #[must_use]
+    pub const fn with_max_media_sources(mut self, sources: usize) -> Self {
+        self.max_media_sources = sources;
+        self
+    }
+}
+
+impl Default for EngineConfig {
+    fn default() -> Self {
+        Self {
+            command_capacity: 64,
+            event_capacity: 128,
+            initial_history_limit: 30,
+            max_media_bytes: 20 * 1024 * 1024,
+            max_media_sources: 2_048,
+        }
+    }
+}
+
+#[derive(Debug, ThisError)]
+pub enum EngineError {
+    #[error("the Matrix client is not authenticated")]
+    Unauthenticated,
+    #[error("command, event, and media source capacities must be nonzero")]
+    ZeroCapacity,
+    #[error("could not build the sync service")]
+    SyncService(#[source] matrix_sdk_ui::sync_service::Error),
+    #[error("the event receiver has closed")]
+    EventReceiverClosed,
+    #[error("engine task {task} panicked")]
+    TaskPanicked { task: String },
+}
+
+impl EngineError {
+    fn failure(&self) -> EngineFailure {
+        EngineFailure {
+            kind: match self {
+                Self::EventReceiverClosed => EngineErrorKind::EventReceiverClosed,
+                Self::TaskPanicked { .. } => EngineErrorKind::Watcher,
+                Self::Unauthenticated | Self::ZeroCapacity | Self::SyncService(_) => {
+                    EngineErrorKind::Other
+                }
+            },
+            message: self.to_string(),
+        }
+    }
+}
+
+#[derive(Clone)]
+enum TaskContext {
+    /// a panic here costs the caller an `Interrupted` answer and nothing else
+    Command(&'static str),
+    /// a panic here takes the engine with it
+    Watcher(&'static str),
+    RoomActor {
+        room_id: OwnedRoomId,
+        generation: u64,
+    },
+}
+
+impl TaskContext {
+    fn label(&self) -> String {
+        match self {
+            Self::Command(name) | Self::Watcher(name) => (*name).to_owned(),
+            Self::RoomActor {
+                room_id,
+                generation,
+            } => format!("room actor {room_id} generation {generation}"),
+        }
+    }
+}
+
+struct TaskRegistry {
+    tasks: JoinSet<()>,
+    contexts: HashMap<TaskId, TaskContext>,
+}
+
+impl TaskRegistry {
+    fn spawn(
+        &mut self,
+        context: TaskContext,
+        task: impl Future<Output = ()> + Send + 'static,
+    ) -> AbortHandle {
+        let handle = self.tasks.spawn(task);
+        self.contexts.insert(handle.id(), context);
+        handle
+    }
+
+    async fn join_next(&mut self) -> Option<(TaskContext, Result<(), JoinError>)> {
+        let result = self.tasks.join_next_with_id().await?;
+        let id = match &result {
+            Ok((id, ())) => *id,
+            Err(error) => error.id(),
+        };
+        let context = self.contexts.remove(&id)?;
+        Some((context, result.map(drop)))
+    }
+
+    async fn shutdown(&mut self) {
+        self.tasks.abort_all();
+        while self.tasks.join_next().await.is_some() {}
+        self.contexts.clear();
+    }
+}
+
+enum RoomSlot {
+    Active {
+        generation: u64,
+        sender: mpsc::Sender<ActorRequest>,
+    },
+    /// opens and closes that arrive while the actor winds down, replayed in order once it's gone
+    Closing {
+        generation: u64,
+        pending: VecDeque<Deferred>,
+    },
+}
+
+impl RoomSlot {
+    const fn generation(&self) -> u64 {
+        match self {
+            Self::Active { generation, .. } | Self::Closing { generation, .. } => *generation,
+        }
+    }
+}
+
+enum Deferred {
+    Open(Responder),
+    Close(Responder),
+}
+
+struct Queues {
+    mutations: mpsc::Receiver<MutationJob>,
+    notifications: mpsc::Receiver<Job<NotificationCommand>>,
+    encryption: mpsc::Receiver<Job<EncryptionCommand>>,
+    session_changes: broadcast::Receiver<SessionChange>,
+}
+
+pub struct Engine {
+    client: Client,
+    sync: Arc<SyncService>,
+    port: DriverPort,
+    config: EngineConfig,
+    media: Arc<MediaService>,
+    tasks: TaskRegistry,
+    rooms: HashMap<OwnedRoomId, RoomSlot>,
+    next_generation: u64,
+    exits: mpsc::UnboundedReceiver<Exited>,
+    exit_sender: mpsc::UnboundedSender<Exited>,
+    mutations: mpsc::Sender<MutationJob>,
+    notifications: mpsc::Sender<Job<NotificationCommand>>,
+    encryption: mpsc::Sender<Job<EncryptionCommand>>,
+    queues: Option<Queues>,
+    /// one progress forwarder per room that has uploaded, and whether it's subscribed yet
+    uploads: HashMap<OwnedRoomId, (AbortHandle, watch::Receiver<bool>)>,
+    stop: Arc<Notify>,
+}
+
+impl Engine {
+    /// the escape hatch for a client you built yourself. `Session` is the usual way in
+    pub async fn from_client(
+        client: Client,
+        config: EngineConfig,
+    ) -> Result<(Self, ClientHandle, EventStream), EngineError> {
+        if client.user_id().is_none() {
+            return Err(EngineError::Unauthenticated);
+        }
+        if config.command_capacity == 0
+            || config.event_capacity == 0
+            || config.max_media_sources == 0
+        {
+            return Err(EngineError::ZeroCapacity);
+        }
+        let session_changes = client.subscribe_to_session_changes();
+        let sync = Arc::new(
+            SyncService::builder(client.clone())
+                .with_offline_mode()
+                .build()
+                .await
+                .map_err(EngineError::SyncService)?,
+        );
+        let media = Arc::new(MediaService::new(
+            client.clone(),
+            config.max_media_bytes,
+            config.max_media_sources,
+        ));
+        let (handle, port, events) = transport_pair(
+            client.clone(),
+            sync.clone(),
+            media.clone(),
+            config.command_capacity,
+            config.event_capacity,
+        );
+        client.send_queue().enable_upload_progress(true);
+        let (exit_sender, exits) = mpsc::unbounded_channel();
+        let (mutations, mutation_queue) = mpsc::channel(config.command_capacity);
+        let (notifications, notification_queue) = mpsc::channel(config.command_capacity);
+        let (encryption, encryption_queue) = mpsc::channel(config.command_capacity);
+        let engine = Self {
+            client,
+            sync,
+            port,
+            config,
+            media,
+            tasks: TaskRegistry {
+                tasks: JoinSet::new(),
+                contexts: HashMap::new(),
+            },
+            rooms: HashMap::new(),
+            next_generation: 0,
+            exits,
+            exit_sender,
+            mutations,
+            notifications,
+            encryption,
+            queues: Some(Queues {
+                mutations: mutation_queue,
+                notifications: notification_queue,
+                encryption: encryption_queue,
+                session_changes,
+            }),
+            uploads: HashMap::new(),
+            stop: Arc::new(Notify::new()),
+        };
+        Ok((engine, handle, events))
+    }
+
+    pub async fn run(mut self) -> Result<(), EngineError> {
+        let events = self.port.event_sender();
+        let user_id = self
+            .client
+            .user_id()
+            .expect("authentication was checked during construction")
+            .to_owned();
+        self.port
+            .connection_sender()
+            .send_replace(ConnectionState::Connecting);
+        for event in [
+            Event::Authenticated { user_id },
+            Event::ConnectionChanged(ConnectionState::Connecting),
+        ] {
+            if events.send(event).await.is_err() {
+                self.shutdown().await;
+                return Err(EngineError::EventReceiverClosed);
+            }
+        }
+        self.start_tasks();
+        self.sync.start().await;
+
+        let mut failure = None;
+        let mut shutdown_reply = None;
+        loop {
+            tokio::select! {
+                biased;
+                () = events.closed() => {
+                    failure = Some(EngineError::EventReceiverClosed);
+                    break;
+                }
+                () = self.stop.notified() => break,
+                request = self.port.recv() => {
+                    let Some(request) = request else { break };
+                    if let Some(reply) = self.dispatch(request).await {
+                        shutdown_reply = Some(reply);
+                        break;
+                    }
+                }
+                Some((context, result)) = self.tasks.join_next(), if !self.tasks.tasks.is_empty() => {
+                    let Err(error) = result else { continue };
+                    if !error.is_panic() {
+                        continue;
+                    }
+                    if let TaskContext::Command(label) = context {
+                        tracing::error!(label, %error, "command task panicked");
+                        continue;
+                    }
+                    failure = Some(EngineError::TaskPanicked { task: context.label() });
+                    break;
+                }
+                Some(exited) = self.exits.recv() => self.room_exited(exited).await,
+            }
+        }
+
+        if let Some(error) = &failure {
+            let _ = events.send(Event::Failed(error.failure())).await;
+        }
+        self.shutdown().await;
+        let _ = events.send(Event::Stopped).await;
+        if let Some(reply) = shutdown_reply {
+            reply.done(Ok(()));
+        }
+        failure.map_or(Ok(()), Err)
+    }
+
+    fn start_tasks(&mut self) {
+        let queues = self.queues.take().expect("engine tasks start once");
+        let client = &self.client;
+        let events = || self.port.event_sender();
+        let watchers: [(&'static str, BoxFuture<'static, ()>); 9] = [
+            (
+                "session change watcher",
+                Box::pin(watchers::session(
+                    queues.session_changes,
+                    events(),
+                    self.stop.clone(),
+                )),
+            ),
+            (
+                "connection state watcher",
+                Box::pin(watchers::connection(
+                    self.sync.state(),
+                    self.sync.clone(),
+                    client.clone(),
+                    events(),
+                    self.port.connection_sender(),
+                )),
+            ),
+            (
+                "send queue watcher",
+                Box::pin(watchers::send_queue_errors(
+                    client.clone(),
+                    client.send_queue().subscribe_errors(),
+                    self.port.connection_sender().subscribe(),
+                )),
+            ),
+            (
+                "encryption state watcher",
+                Box::pin(watchers::encryption(client.clone(), events())),
+            ),
+            (
+                "room list watcher",
+                Box::pin(watchers::rooms(client.clone(), events())),
+            ),
+            (
+                "notification settings watcher",
+                Box::pin(watchers::notification_settings(client.clone(), events())),
+            ),
+            (
+                "room command worker",
+                Box::pin(mutations::run_scheduler(
+                    client.clone(),
+                    queues.mutations,
+                    self.config.command_capacity,
+                )),
+            ),
+            (
+                "notification command worker",
+                Box::pin(commands::run_notifications(
+                    client.clone(),
+                    queues.notifications,
+                )),
+            ),
+            (
+                "encryption command worker",
+                Box::pin(commands::run_encryption(
+                    client.clone(),
+                    events(),
+                    queues.encryption,
+                )),
+            ),
+        ];
+        for (label, task) in watchers {
+            self.tasks.spawn(TaskContext::Watcher(label), task);
+        }
+    }
+
+    /// hands back the shutdown request's responder, which is answered once we've stopped
+    async fn dispatch(&mut self, Request { command, reply }: Request) -> Option<Responder> {
+        let client = self.client.clone();
+        match command {
+            Command::Lifecycle(LifecycleCommand::Shutdown) => return Some(reply),
+            Command::Account(AccountCommand::Logout) => {
+                let events = self.port.event_sender();
+                let stop = self.stop.clone();
+                self.spawn_command("logout", reply, async move {
+                    client
+                        .logout()
+                        .await
+                        .map_err(|source| Error::from_sdk("logout failed", source))?;
+                    let _ = events.send(Event::LoggedOut).await;
+                    stop.notify_one();
+                    Ok(())
+                });
+            }
+            Command::Account(AccountCommand::SetAccountData {
+                event_type,
+                content,
+            }) => enqueue(
+                &self.mutations,
+                Job {
+                    command: Mutation::GlobalAccountData {
+                        event_type,
+                        content,
+                    },
+                    reply,
+                },
+            ),
+            Command::Account(AccountCommand::SetDisplayName(name)) => {
+                self.spawn_command("set display name", reply, async move {
+                    client
+                        .account()
+                        .set_display_name(name.as_deref())
+                        .await
+                        .map_err(|source| Error::from_sdk("setting display name failed", source))
+                });
+            }
+            Command::Account(AccountCommand::SetAvatar(avatar)) => {
+                self.spawn_command("set avatar", reply, async move {
+                    client
+                        .account()
+                        .set_avatar_url(avatar.as_deref())
+                        .await
+                        .map_err(|source| Error::from_sdk("setting avatar failed", source))
+                });
+            }
+            Command::Account(AccountCommand::UploadAvatar { mimetype, bytes }) => {
+                let max_bytes = self.config.max_media_bytes;
+                self.spawn_command("upload avatar", reply, async move {
+                    commands::upload_avatar(&client, &mimetype, bytes, max_bytes).await
+                });
+            }
+            Command::Account(AccountCommand::RenameDevice {
+                device_id,
+                display_name,
+            }) => self.spawn_command("rename device", reply, async move {
+                commands::rename_device(&client, &device_id, &display_name).await
+            }),
+            Command::Account(AccountCommand::DeleteDevices { device_ids, auth }) => {
+                self.spawn_command("delete devices", reply, async move {
+                    commands::delete_devices(&client, &device_ids, auth).await
+                });
+            }
+            Command::Room(RoomCommand::Open(room_id)) => self.open_room(room_id, reply).await,
+            Command::Room(RoomCommand::Close(room_id)) => self.close_room(room_id, reply).await,
+            Command::Room(RoomCommand::SetTyping { room_id, typing }) => {
+                self.spawn_command("typing", reply, async move {
+                    commands::set_typing(&client, &room_id, typing).await
+                });
+            }
+            Command::Room(RoomCommand::CancelSend {
+                room_id,
+                transaction_id,
+            }) => self.spawn_command("cancel send", reply, async move {
+                commands::cancel_send(&client, &room_id, &transaction_id).await
+            }),
+            Command::Room(RoomCommand::RetrySend {
+                room_id,
+                transaction_id,
+            }) => self.spawn_command("retry send", reply, async move {
+                commands::retry_send(&client, &room_id, &transaction_id).await
+            }),
+            Command::Room(command) => enqueue(
+                &self.mutations,
+                Job {
+                    command: Mutation::Room(command),
+                    reply,
+                },
+            ),
+            Command::Timeline(command) => self.route_timeline(command, reply),
+            Command::Media(MediaCommand::Upload(upload)) => self.upload(upload, reply),
+            Command::Encryption(command) => enqueue(&self.encryption, Job { command, reply }),
+            Command::Notification(command) => {
+                enqueue(&self.notifications, Job { command, reply });
+            }
+        }
+        None
+    }
+
+    fn spawn_command(
+        &mut self,
+        label: &'static str,
+        reply: Responder,
+        work: impl Future<Output = Result<(), Error>> + Send + 'static,
+    ) {
+        self.tasks.spawn(TaskContext::Command(label), async move {
+            reply.done(work.await);
+        });
+    }
+
+    fn upload(&mut self, upload: crate::AttachmentUpload, reply: Responder) {
+        let Some(room) = self.client.get_room(upload.timeline_id.room_id()) else {
+            return reply.done(Err(Error::room_unknown()));
+        };
+        let room_id = room.room_id().to_owned();
+        self.uploads
+            .retain(|_, (forwarder, _)| !forwarder.is_finished());
+        let mut ready = match self.uploads.get(&room_id) {
+            Some((_, ready)) => ready.clone(),
+            None => {
+                let (subscribed, ready) = watch::channel(false);
+                let forwarder = self.tasks.spawn(
+                    TaskContext::Command("upload watcher"),
+                    watchers::room_uploads(room.clone(), self.port.event_sender(), subscribed),
+                );
+                self.uploads.insert(room_id, (forwarder, ready.clone()));
+                ready
+            }
+        };
+        let max_bytes = self.config.max_media_bytes;
+        // queueing before the forwarder listens would lose the first progress ticks
+        self.spawn_command("upload", reply, async move {
+            ready
+                .wait_for(|subscribed| *subscribed)
+                .await
+                .map_err(|_| Error::new(ErrorKind::Store, "reading the media send queue failed"))?;
+            media::queue_upload(room, upload, max_bytes).await
+        });
+    }
+
+    fn route_timeline(&mut self, command: TimelineCommand, reply: Responder) {
+        let sender = match self.rooms.get(command.room_id()) {
+            Some(RoomSlot::Active { sender, .. }) => Some(sender.clone()),
+            _ => None,
+        };
+        match (sender, command) {
+            (Some(sender), command) => send_actor(&sender, ActorRequest::Execute(command, reply)),
+            (
+                None,
+                TimelineCommand::MarkRead {
+                    timeline_id,
+                    event_id,
+                },
+            ) => {
+                let client = self.client.clone();
+                self.spawn_command("mark read", reply, async move {
+                    commands::mark_read(&client, &timeline_id, event_id).await
+                });
+            }
+            (None, _) => reply.done(Err(Error::new(ErrorKind::RoomNotOpen, "room is not open"))),
+        }
+    }
+
+    async fn open_room(&mut self, room_id: OwnedRoomId, reply: Responder) {
+        match self.rooms.get_mut(&room_id) {
+            Some(RoomSlot::Active { sender, .. }) => send_actor(sender, ActorRequest::Open(reply)),
+            Some(RoomSlot::Closing { pending, .. }) => {
+                defer(pending, Deferred::Open(reply), self.config.command_capacity);
+            }
+            None => self.start_actor(room_id, reply).await,
+        }
+    }
+
+    async fn close_room(&mut self, room_id: OwnedRoomId, reply: Responder) {
+        let (generation, sender) = match self.rooms.get_mut(&room_id) {
+            None => return reply.done(Ok(())),
+            Some(RoomSlot::Closing { pending, .. }) => {
+                return defer(
+                    pending,
+                    Deferred::Close(reply),
+                    self.config.command_capacity,
+                );
+            }
+            Some(RoomSlot::Active { generation, sender }) => (*generation, sender.clone()),
+        };
+        match sender.try_send(ActorRequest::Close(reply)) {
+            // a closed channel means the actor already left on its own, which is closed enough
+            Ok(()) | Err(mpsc::error::TrySendError::Closed(_)) => {}
+            Err(mpsc::error::TrySendError::Full(request)) => {
+                return request.into_reply().done(Err(Error::new(
+                    ErrorKind::RoomBusy,
+                    "room command queue is full",
+                )));
+            }
+        }
+        self.rooms.insert(
+            room_id,
+            RoomSlot::Closing {
+                generation,
+                pending: VecDeque::new(),
+            },
+        );
+        self.update_room_subscriptions().await;
+    }
+
+    async fn start_actor(&mut self, room_id: OwnedRoomId, reply: Responder) {
+        let Some(room) = self.client.get_room(&room_id) else {
+            return reply.done(Err(Error::room_unknown()));
+        };
+        self.next_generation = self.next_generation.wrapping_add(1);
+        let generation = self.next_generation;
+        let (sender, requests) = mpsc::channel(self.config.command_capacity);
+        let (supervisor, panics) = Supervisor::new();
+        let actor = RoomActor {
+            room_id: room_id.clone(),
+            generation,
+            room,
+            requests,
+            exits: self.exit_sender.clone(),
+            context: SessionContext {
+                events: self.port.event_sender(),
+                media: self.media.clone(),
+                current_user_id: self.client.user_id().map(ToOwned::to_owned),
+                initial_history_limit: self.config.initial_history_limit,
+                supervisor,
+            },
+            panics,
+            opening: vec![reply],
+        };
+        self.rooms
+            .insert(room_id.clone(), RoomSlot::Active { generation, sender });
+        self.tasks.spawn(
+            TaskContext::RoomActor {
+                room_id,
+                generation,
+            },
+            actor.run(),
+        );
+        self.update_room_subscriptions().await;
+    }
+
+    async fn room_exited(
+        &mut self,
+        Exited {
+            room_id,
+            generation,
+        }: Exited,
+    ) {
+        if self
+            .rooms
+            .get(&room_id)
+            .is_none_or(|slot| slot.generation() != generation)
+        {
+            return;
+        }
+        if let Some(RoomSlot::Closing { pending, .. }) = self.rooms.remove(&room_id) {
+            for deferred in pending {
+                match deferred {
+                    Deferred::Open(reply) => self.open_room(room_id.clone(), reply).await,
+                    Deferred::Close(reply) => self.close_room(room_id.clone(), reply).await,
+                }
+            }
+        }
+        self.update_room_subscriptions().await;
+    }
+
+    async fn update_room_subscriptions(&self) {
+        let room_ids = self
+            .rooms
+            .iter()
+            .filter(|(_, slot)| matches!(slot, RoomSlot::Active { .. }))
+            .map(|(room_id, _)| room_id.as_ref())
+            .collect::<Vec<&RoomId>>();
+        self.sync
+            .room_list_service()
+            .subscribe_to_rooms(&room_ids)
+            .await;
+    }
+
+    async fn shutdown(&mut self) {
+        self.port.close();
+        self.tasks.shutdown().await;
+        self.rooms.clear();
+        self.uploads.clear();
+        self.media.clear().await;
+        self.sync.stop().await;
+        self.port
+            .connection_sender()
+            .send_replace(ConnectionState::Stopped);
+        let _ = self
+            .port
+            .event_sender()
+            .send(Event::ConnectionChanged(ConnectionState::Stopped))
+            .await;
+    }
+}
+
+fn send_actor(sender: &mpsc::Sender<ActorRequest>, request: ActorRequest) {
+    if let Err(error) = sender.try_send(request) {
+        let (request, error) = match error {
+            mpsc::error::TrySendError::Full(request) => (
+                request,
+                Error::new(ErrorKind::RoomBusy, "room command queue is full"),
+            ),
+            mpsc::error::TrySendError::Closed(request) => (
+                request,
+                Error::new(ErrorKind::RoomNotOpen, "room is not open"),
+            ),
+        };
+        request.into_reply().done(Err(error));
+    }
+}
+
+fn defer(pending: &mut VecDeque<Deferred>, deferred: Deferred, capacity: usize) {
+    if pending.len() < capacity {
+        return pending.push_back(deferred);
+    }
+    let (Deferred::Open(reply) | Deferred::Close(reply)) = deferred;
+    reply.done(Err(Error::new(
+        ErrorKind::RoomBusy,
+        "room lifecycle queue is full",
+    )));
+}
+
+fn enqueue<T>(sender: &mpsc::Sender<Job<T>>, job: Job<T>) {
+    if let Err(error) = sender.try_send(job) {
+        let (job, error) = match error {
+            mpsc::error::TrySendError::Full(job) => (
+                job,
+                Error::new(ErrorKind::QueueFull, "command queue is full"),
+            ),
+            mpsc::error::TrySendError::Closed(job) => (job, Error::interrupted()),
+        };
+        job.reply.done(Err(error));
+    }
+}

Added file: src/engine/mutations.rs+337 additions@@ -0,0 +1,337 @@
+use std::collections::{HashMap, HashSet, VecDeque};
+
+use matrix_sdk::{
+    Client, Room,
+    ruma::{
+        Int,
+        api::client::room::{
+            Visibility as SdkVisibility,
+            create_room::v3::{Request as CreateRoomRequest, RoomPreset as SdkPreset},
+        },
+        events::{
+            AnyGlobalAccountDataEventContent, GlobalAccountDataEventType, MessageLikeEventType,
+            StateEventType, room::power_levels::RoomPowerLevelsEventContent,
+        },
+        serde::Raw,
+    },
+};
+use ruma::{OwnedRoomId, OwnedUserId};
+use tokio::{sync::mpsc, task::JoinSet};
+
+use super::commands::{Job, guarded};
+use crate::{
+    CommandOutput, CreateRoomOptions, Error, ErrorKind, PowerLevelChanges, RoomCommand, RoomPreset,
+    RoomVisibility,
+};
+
+/// state changes that must not race each other. same room, same alias, same dm
+/// partner or same account data type run in order, everything else runs at once
+pub(super) enum Mutation {
+    Room(RoomCommand),
+    GlobalAccountData {
+        event_type: GlobalAccountDataEventType,
+        content: Raw<AnyGlobalAccountDataEventContent>,
+    },
+}
+
+pub(super) type MutationJob = Job<Mutation>;
+
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+enum Key {
+    Room(OwnedRoomId),
+    Alias(String),
+    Direct(OwnedUserId),
+    AccountData(String),
+    Independent(u64),
+}
+
+pub(super) async fn run_scheduler(
+    client: Client,
+    mut jobs: mpsc::Receiver<MutationJob>,
+    queue_limit: usize,
+) {
+    let mut waiting = HashMap::<Key, VecDeque<MutationJob>>::new();
+    let mut running = HashSet::<Key>::new();
+    let mut tasks = JoinSet::<Key>::new();
+    let mut queued = 0_usize;
+    let mut independent = 0_u64;
+    let mut receiving = true;
+    while receiving || !tasks.is_empty() {
+        tokio::select! {
+            biased;
+            Some(finished) = tasks.join_next(), if !tasks.is_empty() => {
+                // a job's own panic is caught inside it, so this is only ever a key
+                let Ok(key) = finished else { continue };
+                let next = waiting.get_mut(&key).and_then(VecDeque::pop_front);
+                if waiting.get(&key).is_some_and(VecDeque::is_empty) {
+                    waiting.remove(&key);
+                }
+                match next {
+                    Some(job) => {
+                        queued -= 1;
+                        spawn(&mut tasks, &client, key, job);
+                    }
+                    None => {
+                        running.remove(&key);
+                    }
+                }
+            }
+            job = jobs.recv(), if receiving => {
+                let Some(job) = job else {
+                    receiving = false;
+                    continue;
+                };
+                let key = key(&job.command).unwrap_or_else(|| {
+                    independent += 1;
+                    Key::Independent(independent)
+                });
+                if running.insert(key.clone()) {
+                    spawn(&mut tasks, &client, key, job);
+                } else if queued < queue_limit {
+                    waiting.entry(key).or_default().push_back(job);
+                    queued += 1;
+                } else {
+                    job.reply.done(Err(Error::new(
+                        ErrorKind::QueueFull,
+                        "room command queue is full",
+                    )));
+                }
+            }
+        }
+    }
+}
+
+fn key(mutation: &Mutation) -> Option<Key> {
+    let room_id = match mutation {
+        Mutation::GlobalAccountData { event_type, .. } => {
+            return Some(Key::AccountData(event_type.to_string()));
+        }
+        Mutation::Room(RoomCommand::Join { room, .. }) => {
+            return Some(match OwnedRoomId::try_from(room.clone()) {
+                Ok(room_id) => Key::Room(room_id),
+                Err(alias) => Key::Alias(alias.to_string()),
+            });
+        }
+        Mutation::Room(RoomCommand::CreateDirect(user_id)) => {
+            return Some(Key::Direct(user_id.clone()));
+        }
+        Mutation::Room(
+            RoomCommand::Leave(room_id)
+            | RoomCommand::Forget(room_id)
+            | RoomCommand::AcceptInvite(room_id)
+            | RoomCommand::RejectInvite(room_id)
+            | RoomCommand::InviteUser { room_id, .. }
+            | RoomCommand::KickUser { room_id, .. }
+            | RoomCommand::BanUser { room_id, .. }
+            | RoomCommand::UnbanUser { room_id, .. }
+            | RoomCommand::SetPowerLevels { room_id, .. }
+            | RoomCommand::SetUserPowerLevel { room_id, .. }
+            | RoomCommand::SetAccountData { room_id, .. },
+        ) => room_id,
+        Mutation::Room(_) => return None,
+    };
+    Some(Key::Room(room_id.clone()))
+}
+
+fn spawn(tasks: &mut JoinSet<Key>, client: &Client, key: Key, job: MutationJob) {
+    let client = client.clone();
+    tasks.spawn(async move {
+        let Job { command, reply } = job;
+        reply.send(guarded("room command", execute(&client, command)).await);
+        key
+    });
+}
+
+async fn execute(client: &Client, mutation: Mutation) -> Result<CommandOutput, Error> {
+    let command = match mutation {
+        Mutation::GlobalAccountData {
+            event_type,
+            content,
+        } => {
+            client
+                .account()
+                .set_account_data_raw(event_type, content)
+                .await
+                .map_err(|source| Error::from_sdk("writing account data failed", source))?;
+            return Ok(CommandOutput::Done);
+        }
+        Mutation::Room(command) => command,
+    };
+    let room = |room_id: &OwnedRoomId| client.get_room(room_id).ok_or_else(Error::room_unknown);
+    let joined = |room: Room| CommandOutput::Room(room.room_id().to_owned());
+    let sdk = |message: &'static str| move |source| Error::from_sdk(message, source);
+    match command {
+        RoomCommand::Join { room, via } => client
+            .join_room_by_id_or_alias(&room, &via)
+            .await
+            .map(joined)
+            .map_err(sdk("joining room failed")),
+        RoomCommand::Leave(room_id) => room(&room_id)?
+            .leave()
+            .await
+            .map(done)
+            .map_err(sdk("leaving room failed")),
+        RoomCommand::Forget(room_id) => room(&room_id)?
+            .forget()
+            .await
+            .map(done)
+            .map_err(sdk("forgetting room failed")),
+        RoomCommand::AcceptInvite(room_id) => room(&room_id)?
+            .join()
+            .await
+            .map(done)
+            .map_err(sdk("accepting invite failed")),
+        RoomCommand::RejectInvite(room_id) => room(&room_id)?
+            .leave()
+            .await
+            .map(done)
+            .map_err(sdk("rejecting invite failed")),
+        RoomCommand::InviteUser { room_id, user_id } => room(&room_id)?
+            .invite_user_by_id(&user_id)
+            .await
+            .map(done)
+            .map_err(sdk("inviting user failed")),
+        RoomCommand::KickUser {
+            room_id,
+            user_id,
+            reason,
+        } => room(&room_id)?
+            .kick_user(&user_id, reason.as_deref())
+            .await
+            .map(done)
+            .map_err(sdk("kicking user failed")),
+        RoomCommand::BanUser {
+            room_id,
+            user_id,
+            reason,
+        } => room(&room_id)?
+            .ban_user(&user_id, reason.as_deref())
+            .await
+            .map(done)
+            .map_err(sdk("banning user failed")),
+        RoomCommand::UnbanUser {
+            room_id,
+            user_id,
+            reason,
+        } => room(&room_id)?
+            .unban_user(&user_id, reason.as_deref())
+            .await
+            .map(done)
+            .map_err(sdk("unbanning user failed")),
+        RoomCommand::SetPowerLevels { room_id, changes } => {
+            apply_power_level_changes(&room(&room_id)?, changes)
+                .await
+                .map(done)
+        }
+        RoomCommand::SetUserPowerLevel {
+            room_id,
+            user_id,
+            level,
+        } => room(&room_id)?
+            .update_power_levels(vec![(&user_id, power_level(level)?)])
+            .await
+            .map(done)
+            .map_err(sdk("updating user power level failed")),
+        RoomCommand::SetAccountData {
+            room_id,
+            event_type,
+            content,
+        } => room(&room_id)?
+            .set_account_data_raw(event_type, content)
+            .await
+            .map(done)
+            .map_err(sdk("writing room account data failed")),
+        RoomCommand::Create(options) => client
+            .create_room(create_room_request(options))
+            .await
+            .map(joined)
+            .map_err(sdk("creating room failed")),
+        RoomCommand::CreateDirect(user_id) => match client.get_dm_room(&user_id) {
+            Some(existing) => Ok(joined(existing)),
+            None => client
+                .create_dm(&user_id)
+                .await
+                .map(joined)
+                .map_err(sdk("creating direct room failed")),
+        },
+        _ => Err(Error::new(ErrorKind::Other, "room command was misrouted")),
+    }
+}
+
+/// one state event carrying every requested change, since the sdk's own patcher is private
+async fn apply_power_level_changes(room: &Room, changes: PowerLevelChanges) -> Result<(), Error> {
+    let mut levels = room
+        .power_levels()
+        .await
+        .map_err(|source| Error::from_sdk("reading power levels failed", source.into()))?;
+    for (target, value) in [
+        (&mut levels.ban, changes.ban),
+        (&mut levels.invite, changes.invite),
+        (&mut levels.kick, changes.kick),
+        (&mut levels.redact, changes.redact),
+        (&mut levels.events_default, changes.events_default),
+        (&mut levels.state_default, changes.state_default),
+        (&mut levels.users_default, changes.users_default),
+        (&mut levels.notifications.room, changes.room_notification),
+    ] {
+        if let Some(value) = value {
+            *target = power_level(value)?;
+        }
+    }
+    for (event_type, value) in [
+        (StateEventType::RoomName.into(), changes.room_name),
+        (StateEventType::RoomAvatar.into(), changes.room_avatar),
+        (StateEventType::RoomTopic.into(), changes.room_topic),
+        (StateEventType::SpaceChild.into(), changes.space_child),
+        (MessageLikeEventType::Beacon.into(), changes.beacon),
+        (StateEventType::BeaconInfo.into(), changes.beacon_info),
+    ] {
+        if let Some(value) = value {
+            levels.events.insert(event_type, power_level(value)?);
+        }
+    }
+    let content = RoomPowerLevelsEventContent::try_from(levels).map_err(|source| {
+        Error::with_source(
+            ErrorKind::Invalid,
+            "normalising power levels failed",
+            source,
+        )
+    })?;
+    room.send_state_event(content)
+        .await
+        .map(drop)
+        .map_err(|source| Error::from_sdk("updating power levels failed", source))
+}
+
+fn done<T>(_: T) -> CommandOutput {
+    CommandOutput::Done
+}
+
+fn power_level(value: i64) -> Result<Int, Error> {
+    value.try_into().map_err(|source| {
+        Error::with_source(
+            ErrorKind::Invalid,
+            "power level is outside the Matrix integer range",
+            source,
+        )
+    })
+}
+
+fn create_room_request(options: CreateRoomOptions) -> CreateRoomRequest {
+    let mut request = CreateRoomRequest::new();
+    request.name = options.name;
+    request.topic = options.topic;
+    request.room_alias_name = options.alias_localpart;
+    request.invite = options.invite;
+    request.is_direct = options.direct;
+    request.visibility = match options.visibility {
+        RoomVisibility::Private => SdkVisibility::Private,
+        RoomVisibility::Public => SdkVisibility::Public,
+    };
+    request.preset = options.preset.map(|preset| match preset {
+        RoomPreset::PrivateChat => SdkPreset::PrivateChat,
+        RoomPreset::TrustedPrivateChat => SdkPreset::TrustedPrivateChat,
+        RoomPreset::PublicChat => SdkPreset::PublicChat,
+    });
+    request
+}

Added file: src/engine/room.rs+414 additions@@ -0,0 +1,414 @@
+use std::collections::{HashMap, VecDeque};
+
+use matrix_sdk::{Room, RoomState};
+use matrix_sdk_ui::timeline::{RoomExt, Timeline, TimelineFocus, TimelineReadReceiptTracking};
+use ruma::{OwnedEventId, OwnedRoomId};
+use tokio::{
+    sync::mpsc,
+    task::{AbortHandle, JoinSet},
+};
+
+use super::timeline::{SessionContext, TimelineSession};
+use crate::{
+    Error, ErrorKind, Event, TimelineCommand, TimelineId, TypingState, transport::Responder,
+};
+
+pub(super) enum ActorRequest {
+    /// opening an open room answers with a fresh reset
+    Open(Responder),
+    Execute(TimelineCommand, Responder),
+    Close(Responder),
+}
+
+impl ActorRequest {
+    pub(super) fn into_reply(self) -> Responder {
+        match self {
+            Self::Open(reply) | Self::Execute(_, reply) | Self::Close(reply) => reply,
+        }
+    }
+}
+
+pub(super) struct Exited {
+    pub(super) room_id: OwnedRoomId,
+    pub(super) generation: u64,
+}
+
+pub(super) struct RoomActor {
+    pub(super) room_id: OwnedRoomId,
+    pub(super) generation: u64,
+    pub(super) room: Room,
+    pub(super) requests: mpsc::Receiver<ActorRequest>,
+    pub(super) exits: mpsc::UnboundedSender<Exited>,
+    pub(super) context: SessionContext,
+    pub(super) panics: mpsc::UnboundedReceiver<&'static str>,
+    pub(super) opening: Vec<Responder>,
+}
+
+impl RoomActor {
+    pub(super) async fn run(mut self) {
+        let exits = self.exits.clone();
+        let exited = Exited {
+            room_id: self.room_id.clone(),
+            generation: self.generation,
+        };
+        self.serve().await;
+        let _ = exits.send(exited);
+    }
+
+    async fn serve(&mut self) {
+        let timeline = match build_timeline(
+            &self.room,
+            TimelineFocus::Live {
+                hide_threaded_events: true,
+            },
+        )
+        .await
+        {
+            Ok(timeline) => timeline,
+            Err(error) => return self.refuse_everything(error).await,
+        };
+        let Ok(room_timeline) = TimelineSession::start(
+            TimelineId::Room(self.room_id.clone()),
+            timeline,
+            self.context.clone(),
+        )
+        .await
+        else {
+            return;
+        };
+        for reply in self.opening.drain(..) {
+            reply.done(Ok(()));
+        }
+        let (typing_guard, typing) = self.room.subscribe_to_typing_notifications();
+        let typing_watcher = self.context.supervisor.spawn(
+            "typing watcher",
+            watch_typing(self.room_id.clone(), typing, self.context.events.clone()),
+        );
+        let mut timelines = Timelines {
+            room: room_timeline,
+            threads: Threads::new(self.requests.max_capacity()),
+            work: JoinSet::new(),
+        };
+        let close = self.serve_open(&mut timelines).await;
+
+        // let redactions and receipts that already left finish rather than lie about them
+        while timelines.work.join_next().await.is_some() {}
+        drop(typing_guard);
+        typing_watcher.abort();
+        timelines.threads.close().await;
+        timelines.room.close().await;
+        if let Some(reply) = close {
+            reply.done(Ok(()));
+        }
+    }
+
+    /// returns the close request's responder, if a close is why we stopped
+    async fn serve_open(&mut self, timelines: &mut Timelines) -> Option<Responder> {
+        let mut room_info = self.room.subscribe_info();
+        loop {
+            tokio::select! {
+                Some(info) = room_info.next() => {
+                    if matches!(info.state(), RoomState::Left | RoomState::Banned) {
+                        tracing::debug!(room_id = %self.room_id, "room actor stopped because we left the room");
+                        return None;
+                    }
+                }
+                request = self.requests.recv() => match request {
+                    None => return None,
+                    Some(ActorRequest::Close(reply)) => return Some(reply),
+                    Some(ActorRequest::Open(reply)) => reply.done(timelines.room.resync().await),
+                    Some(ActorRequest::Execute(command, reply)) => {
+                        timelines.execute(command, reply, &self.room).await;
+                    }
+                },
+                Some(built) = timelines.threads.builds.join_next(), if !timelines.threads.builds.is_empty() => {
+                    timelines.thread_built(built, &self.room_id, &self.context).await;
+                }
+                Some(label) = self.panics.recv() => panic!("{label} panicked in room {}", self.room_id),
+                Some(done) = timelines.work.join_next(), if !timelines.work.is_empty() => {
+                    if let Err(error) = done && error.is_panic() {
+                        tracing::warn!(room_id = %self.room_id, %error, "timeline operation panicked");
+                    }
+                }
+            }
+        }
+    }
+
+    async fn refuse_everything(&mut self, error: matrix_sdk_ui::timeline::Error) {
+        tracing::warn!(%error, room_id = %self.room_id, "room actor could not build its timeline");
+        let error = Error::with_source(ErrorKind::Timeline, "room timeline build failed", error);
+        for reply in self.opening.drain(..) {
+            reply.done(Err(error.clone()));
+        }
+        self.requests.close();
+        while let Some(request) = self.requests.recv().await {
+            request.into_reply().done(Err(error.clone()));
+        }
+    }
+}
+
+async fn build_timeline(
+    room: &Room,
+    focus: TimelineFocus,
+) -> Result<Timeline, matrix_sdk_ui::timeline::Error> {
+    room.timeline_builder()
+        .with_focus(focus)
+        .track_read_marker_and_receipts(TimelineReadReceiptTracking::AllEvents)
+        .build()
+        .await
+}
+
+async fn watch_typing(
+    room_id: OwnedRoomId,
+    mut typing: tokio::sync::broadcast::Receiver<Vec<ruma::OwnedUserId>>,
+    events: crate::transport::EventSender,
+) {
+    loop {
+        match typing.recv().await {
+            Ok(users) => {
+                let state = TypingState {
+                    room_id: room_id.clone(),
+                    users,
+                };
+                if events.send(Event::TypingChanged(state)).await.is_err() {
+                    return;
+                }
+            }
+            Err(tokio::sync::broadcast::error::RecvError::Lagged(skipped)) => {
+                tracing::warn!(%room_id, skipped, "typing watcher lagged");
+            }
+            Err(tokio::sync::broadcast::error::RecvError::Closed) => return,
+        }
+    }
+}
+
+struct Timelines {
+    room: TimelineSession,
+    threads: Threads,
+    work: JoinSet<()>,
+}
+
+impl Timelines {
+    async fn execute(&mut self, command: TimelineCommand, reply: Responder, room: &Room) {
+        match command {
+            TimelineCommand::OpenThread { root_event_id, .. } => {
+                self.threads.open(root_event_id, reply, room);
+            }
+            TimelineCommand::CloseThread { root_event_id, .. } => {
+                reply.done(self.threads.close_one(&root_event_id).await);
+            }
+            TimelineCommand::Resync {
+                timeline_id: TimelineId::Room(_),
+            } => reply.done(self.room.resync().await),
+            command => {
+                let root = command
+                    .timeline_id()
+                    .and_then(TimelineId::thread_root)
+                    .cloned();
+                let Some(root) = root else {
+                    return self.room.execute(command, reply, &mut self.work).await;
+                };
+                match self.threads.route(root, command, reply) {
+                    Routed::Open(session, TimelineCommand::Resync { .. }, reply) => {
+                        reply.done(session.resync().await);
+                    }
+                    Routed::Open(session, command, reply) => {
+                        session.execute(command, reply, &mut self.work).await;
+                    }
+                    Routed::Queued => {}
+                }
+            }
+        }
+    }
+
+    async fn thread_built(
+        &mut self,
+        built: Result<Built, tokio::task::JoinError>,
+        room_id: &OwnedRoomId,
+        context: &SessionContext,
+    ) {
+        let Some((root, queued, timeline)) = self.threads.built(built) else {
+            return;
+        };
+        let timeline = match timeline {
+            Ok(timeline) => timeline,
+            Err(error) => {
+                tracing::warn!(%error, %room_id, %root, "thread timeline build failed");
+                let error =
+                    Error::with_source(ErrorKind::Timeline, "thread timeline build failed", error);
+                for (_, reply) in queued {
+                    reply.done(Err(error.clone()));
+                }
+                return;
+            }
+        };
+        let id = TimelineId::thread(room_id.clone(), root.clone());
+        let Ok(session) = TimelineSession::start(id, timeline, context.clone()).await else {
+            return;
+        };
+        let session = self
+            .threads
+            .open
+            .entry(root)
+            .insert_entry(session)
+            .into_mut();
+        for (command, reply) in queued {
+            match command {
+                None => reply.done(Ok(())),
+                Some(TimelineCommand::Resync { .. }) => reply.done(session.resync().await),
+                Some(command) => session.execute(command, reply, &mut self.work).await,
+            }
+        }
+    }
+}
+
+type Built = (
+    OwnedEventId,
+    u64,
+    Result<Timeline, matrix_sdk_ui::timeline::Error>,
+);
+
+/// `None` is the open itself, everything else waits behind it
+type Queued = VecDeque<(Option<TimelineCommand>, Responder)>;
+
+enum Routed<'a> {
+    Open(&'a mut TimelineSession, TimelineCommand, Responder),
+    Queued,
+}
+
+struct OpeningThread {
+    generation: u64,
+    build: AbortHandle,
+    queued: Queued,
+}
+
+struct Threads {
+    open: HashMap<OwnedEventId, TimelineSession>,
+    opening: HashMap<OwnedEventId, OpeningThread>,
+    builds: JoinSet<Built>,
+    next_generation: u64,
+    queued: usize,
+    capacity: usize,
+}
+
+impl Threads {
+    fn new(capacity: usize) -> Self {
+        Self {
+            open: HashMap::new(),
+            opening: HashMap::new(),
+            builds: JoinSet::new(),
+            next_generation: 0,
+            queued: 0,
+            capacity,
+        }
+    }
+
+    fn enqueue(&mut self, root: &OwnedEventId, command: Option<TimelineCommand>, reply: Responder) {
+        if self.queued >= self.capacity {
+            return reply.done(Err(Error::new(
+                ErrorKind::QueueFull,
+                "thread command queue is full",
+            )));
+        }
+        let Some(opening) = self.opening.get_mut(root) else {
+            return reply.done(Err(Error::new(
+                ErrorKind::TimelineNotOpen,
+                "thread timeline is not open",
+            )));
+        };
+        opening.queued.push_back((command, reply));
+        self.queued += 1;
+    }
+
+    fn open(&mut self, root: OwnedEventId, reply: Responder, room: &Room) {
+        if self.open.contains_key(&root) {
+            return reply.done(Ok(()));
+        }
+        if !self.opening.contains_key(&root) {
+            let generation = self.next_generation;
+            self.next_generation = self.next_generation.wrapping_add(1);
+            let room = room.clone();
+            let build_root = root.clone();
+            let build = self.builds.spawn(async move {
+                let focus = TimelineFocus::Thread {
+                    root_event_id: build_root.clone(),
+                };
+                (build_root, generation, build_timeline(&room, focus).await)
+            });
+            self.opening.insert(
+                root.clone(),
+                OpeningThread {
+                    generation,
+                    build,
+                    queued: VecDeque::new(),
+                },
+            );
+        }
+        self.enqueue(&root, None, reply);
+    }
+
+    fn route(
+        &mut self,
+        root: OwnedEventId,
+        command: TimelineCommand,
+        reply: Responder,
+    ) -> Routed<'_> {
+        if !self.open.contains_key(&root) {
+            self.enqueue(&root, Some(command), reply);
+            return Routed::Queued;
+        }
+        let session = self.open.get_mut(&root).expect("thread was just checked");
+        Routed::Open(session, command, reply)
+    }
+
+    /// `None` when the build belongs to a thread that was closed while it ran
+    fn built(
+        &mut self,
+        built: Result<Built, tokio::task::JoinError>,
+    ) -> Option<(
+        OwnedEventId,
+        Queued,
+        Result<Timeline, matrix_sdk_ui::timeline::Error>,
+    )> {
+        let (root, generation, timeline) = match built {
+            Ok(built) => built,
+            Err(error) if error.is_cancelled() => return None,
+            Err(error) => std::panic::resume_unwind(error.into_panic()),
+        };
+        if self
+            .opening
+            .get(&root)
+            .is_none_or(|opening| opening.generation != generation)
+        {
+            return None;
+        }
+        let opening = self.opening.remove(&root)?;
+        self.queued -= opening.queued.len();
+        Some((root, opening.queued, timeline))
+    }
+
+    async fn close_one(&mut self, root: &OwnedEventId) -> Result<(), Error> {
+        if let Some(session) = self.open.remove(root) {
+            session.close().await;
+            return Ok(());
+        }
+        let Some(opening) = self.opening.remove(root) else {
+            return Err(Error::new(
+                ErrorKind::TimelineNotOpen,
+                "thread timeline is not open",
+            ));
+        };
+        opening.build.abort();
+        self.queued -= opening.queued.len();
+        Ok(())
+    }
+
+    async fn close(&mut self) {
+        self.builds.abort_all();
+        while self.builds.join_next().await.is_some() {}
+        self.opening.clear();
+        for (_, session) in self.open.drain() {
+            session.close().await;
+        }
+    }
+}

Added file: src/engine/timeline.rs+406 additions@@ -0,0 +1,406 @@
+use std::{future::Future, panic::AssertUnwindSafe, pin::Pin, sync::Arc};
+
+use futures_util::{FutureExt, StreamExt};
+use matrix_sdk::{
+    room::edit::EditedContent,
+    room::reply::{EnforceThread, Reply as SdkReply},
+    ruma::{
+        api::client::receipt::create_receipt::v3::ReceiptType,
+        events::{
+            Mentions,
+            room::message::{
+                AddMentions, Relation, ReplyWithinThread, RoomMessageEventContentWithoutRelation,
+            },
+        },
+    },
+};
+use matrix_sdk_ui::timeline::{Timeline, TimelineEventItemId};
+use ruma::{OwnedEventId, OwnedUserId};
+use tokio::{
+    sync::mpsc,
+    task::{JoinHandle, JoinSet},
+};
+
+use crate::{
+    Error, ErrorKind, Event, HistoryState, MessageContent, MessageEditContent, MessageMentions,
+    RichText, TimelineCommand, TimelineId,
+    engine::MediaService,
+    normalise::{MediaScope, normalise_timeline, normalise_timeline_diffs},
+    transport::{EventSender, Responder, SendEventError},
+};
+
+const PAGINATION_QUEUE: usize = 32;
+
+/// long-lived tasks inside a room actor report panics here so the actor can die loudly
+#[derive(Clone)]
+pub(super) struct Supervisor(mpsc::UnboundedSender<&'static str>);
+
+impl Supervisor {
+    pub(super) fn new() -> (Self, mpsc::UnboundedReceiver<&'static str>) {
+        let (sender, receiver) = mpsc::unbounded_channel();
+        (Self(sender), receiver)
+    }
+
+    pub(super) fn spawn(
+        &self,
+        label: &'static str,
+        task: impl Future<Output = ()> + Send + 'static,
+    ) -> JoinHandle<()> {
+        let panics = self.0.clone();
+        tokio::spawn(async move {
+            if AssertUnwindSafe(task).catch_unwind().await.is_err() {
+                let _ = panics.send(label);
+            }
+        })
+    }
+}
+
+/// what a timeline session needs from the room that owns it
+#[derive(Clone)]
+pub(super) struct SessionContext {
+    pub(super) events: EventSender,
+    pub(super) media: Arc<MediaService>,
+    pub(super) current_user_id: Option<OwnedUserId>,
+    pub(super) initial_history_limit: u16,
+    pub(super) supervisor: Supervisor,
+}
+
+pub(super) struct TimelineSession {
+    pub(super) id: TimelineId,
+    timeline: Arc<Timeline>,
+    context: SessionContext,
+    scope: MediaScope,
+    watcher: JoinHandle<()>,
+    pagination: mpsc::Sender<PaginationRequest>,
+    pagination_worker: JoinHandle<()>,
+}
+
+struct PaginationRequest {
+    limit: u16,
+    reply: Option<Responder>,
+}
+
+impl TimelineSession {
+    pub(super) async fn start(
+        id: TimelineId,
+        timeline: Timeline,
+        context: SessionContext,
+    ) -> Result<Self, SendEventError> {
+        let timeline = Arc::new(timeline);
+        let scope = MediaScope::new();
+        let watcher = start_watcher(&id, &timeline, &context, &scope).await?;
+        let (pagination, requests) = mpsc::channel(PAGINATION_QUEUE);
+        let pagination_worker = context.supervisor.spawn(
+            "pagination worker",
+            run_pagination(
+                requests,
+                timeline.clone(),
+                context.events.clone(),
+                id.clone(),
+            ),
+        );
+        let session = Self {
+            id,
+            timeline,
+            scope,
+            watcher,
+            pagination,
+            pagination_worker,
+            context,
+        };
+        if session.context.initial_history_limit > 0 {
+            session.paginate(session.context.initial_history_limit, None);
+        }
+        Ok(session)
+    }
+
+    /// swaps in a fresh watcher. the old one is dead before the reset goes out,
+    /// so no stale diff can land after it
+    pub(super) async fn resync(&mut self) -> Result<(), Error> {
+        self.watcher.abort();
+        let _ = (&mut self.watcher).await;
+        self.watcher = start_watcher(&self.id, &self.timeline, &self.context, &self.scope)
+            .await
+            .map_err(|_| Error::new(ErrorKind::Timeline, "timeline reset could not be sent"))?;
+        Ok(())
+    }
+
+    pub(super) fn paginate(&self, limit: u16, reply: Option<Responder>) {
+        if let Err(error) = self.pagination.try_send(PaginationRequest { limit, reply }) {
+            let (request, error) = match error {
+                mpsc::error::TrySendError::Full(request) => (
+                    request,
+                    Error::new(ErrorKind::QueueFull, "pagination queue is full"),
+                ),
+                mpsc::error::TrySendError::Closed(request) => (
+                    request,
+                    Error::new(ErrorKind::TimelineNotOpen, "timeline is closing"),
+                ),
+            };
+            if let Some(reply) = request.reply {
+                reply.done(Err(error));
+            }
+        }
+    }
+
+    /// pending paginations answer `Interrupted` as their responders drop
+    pub(super) async fn close(mut self) {
+        self.context.media.release(&self.scope).await;
+        self.pagination_worker.abort();
+        let _ = (&mut self.pagination_worker).await;
+        self.watcher.abort();
+        let _ = (&mut self.watcher).await;
+    }
+
+    pub(super) async fn execute(
+        &self,
+        command: TimelineCommand,
+        reply: Responder,
+        work: &mut JoinSet<()>,
+    ) {
+        let timeline = self.timeline.clone();
+        let thread_root = self.id.thread_root().cloned();
+        let background: Pin<Box<dyn Future<Output = Result<(), Error>> + Send>> = match command {
+            TimelineCommand::Paginate { limit, .. } => return self.paginate(limit, Some(reply)),
+            // network-bound, so it runs beside the actor instead of queueing the room behind it
+            TimelineCommand::Redact {
+                event_id, reason, ..
+            } => Box::pin(async move {
+                timeline
+                    .redact(&TimelineEventItemId::EventId(event_id), reason.as_deref())
+                    .await
+                    .map_err(timeline_error)
+            }),
+            TimelineCommand::ToggleReaction { event_id, key, .. } => Box::pin(async move {
+                timeline
+                    .toggle_reaction(&TimelineEventItemId::EventId(event_id), &key)
+                    .await
+                    .map(drop)
+                    .map_err(timeline_error)
+            }),
+            TimelineCommand::MarkRead { event_id, .. } => Box::pin(async move {
+                let receipt_failed =
+                    |source| Error::from_sdk("sending read receipt failed", source);
+                timeline
+                    .send_single_receipt(ReceiptType::Read, event_id.clone())
+                    .await
+                    .map_err(receipt_failed)?;
+                if thread_root.is_none() {
+                    timeline
+                        .send_single_receipt(ReceiptType::FullyRead, event_id)
+                        .await
+                        .map_err(receipt_failed)?;
+                }
+                Ok(())
+            }),
+            command => return reply.done(self.execute_serial(command).await),
+        };
+        work.spawn(async move { reply.done(background.await) });
+    }
+
+    /// sends stay on the actor so they hit the send queue in the order they were asked for
+    async fn execute_serial(&self, command: TimelineCommand) -> Result<(), Error> {
+        let timeline = &self.timeline;
+        match command {
+            TimelineCommand::Send { content, .. } => {
+                let body = match &content {
+                    MessageContent::Text { content, .. }
+                    | MessageContent::Emote { content, .. }
+                    | MessageContent::Reply { content, .. } => &content.body,
+                };
+                if body.trim().is_empty() {
+                    return Err(Error::new(ErrorKind::EmptyBody, "message body is empty"));
+                }
+                let content = match content {
+                    MessageContent::Text { content, mentions } => {
+                        message_content(content, mentions, false).with_relation(None)
+                    }
+                    MessageContent::Emote { content, mentions } => {
+                        message_content(content, mentions, true).with_relation(None)
+                    }
+                    MessageContent::Reply {
+                        event_id,
+                        content,
+                        mentions,
+                        notify_replied_to,
+                    } => {
+                        self.reply_content(event_id, content, mentions, notify_replied_to)
+                            .await?
+                    }
+                };
+                timeline
+                    .send(content.into())
+                    .await
+                    .map(drop)
+                    .map_err(timeline_error)
+            }
+            TimelineCommand::Edit {
+                event_id, content, ..
+            } => {
+                let (content, mentions, emote) = match content {
+                    MessageEditContent::Text { content, mentions } => (content, mentions, false),
+                    MessageEditContent::Emote { content, mentions } => (content, mentions, true),
+                };
+                if content.body.trim().is_empty() {
+                    return Err(Error::new(ErrorKind::EmptyBody, "message body is empty"));
+                }
+                timeline
+                    .edit(
+                        &TimelineEventItemId::EventId(event_id),
+                        EditedContent::RoomMessage(message_content(content, mentions, emote)),
+                    )
+                    .await
+                    .map_err(timeline_error)
+            }
+            _ => Err(Error::new(
+                ErrorKind::Other,
+                "timeline command was misrouted",
+            )),
+        }
+    }
+
+    async fn reply_content(
+        &self,
+        event_id: OwnedEventId,
+        content: RichText,
+        mentions: MessageMentions,
+        notify_replied_to: bool,
+    ) -> Result<matrix_sdk::ruma::events::room::message::RoomMessageEventContent, Error> {
+        let thread_root = self.id.thread_root();
+        let content = self
+            .timeline
+            .room()
+            .make_reply_event(
+                message_content(content, mentions, false),
+                SdkReply {
+                    event_id,
+                    enforce_thread: if thread_root.is_some() {
+                        EnforceThread::Threaded(ReplyWithinThread::Yes)
+                    } else {
+                        EnforceThread::MaybeThreaded
+                    },
+                    add_mentions: if notify_replied_to {
+                        AddMentions::Yes
+                    } else {
+                        AddMentions::No
+                    },
+                },
+            )
+            .await
+            .map_err(|source| {
+                Error::with_source(ErrorKind::Timeline, "reply operation failed", source)
+            })?;
+        if let Some(thread_root) = thread_root
+            && !matches!(
+                content.relates_to.as_ref(),
+                Some(Relation::Thread(thread)) if &thread.event_id == thread_root
+            )
+        {
+            return Err(Error::new(
+                ErrorKind::Invalid,
+                "reply target does not belong to the selected thread",
+            ));
+        }
+        Ok(content)
+    }
+}
+
+impl Drop for TimelineSession {
+    fn drop(&mut self) {
+        self.watcher.abort();
+        self.pagination_worker.abort();
+    }
+}
+
+async fn start_watcher(
+    id: &TimelineId,
+    timeline: &Arc<Timeline>,
+    context: &SessionContext,
+    scope: &MediaScope,
+) -> Result<JoinHandle<()>, SendEventError> {
+    let (items, mut stream) = timeline.subscribe().await;
+    let current_user_id = context.current_user_id.clone();
+    let normalised = normalise_timeline(items.iter(), current_user_id.as_deref(), scope);
+    context.media.register(normalised.media).await;
+    context
+        .events
+        .send(Event::TimelineReset {
+            timeline_id: id.clone(),
+            items: normalised.items,
+        })
+        .await?;
+    let id = id.clone();
+    let events = context.events.clone();
+    let media = context.media.clone();
+    let scope = scope.clone();
+    Ok(context.supervisor.spawn("timeline watcher", async move {
+        while let Some(diffs) = stream.next().await {
+            let normalised = normalise_timeline_diffs(diffs, current_user_id.as_deref(), &scope);
+            media.register(normalised.media).await;
+            let event = Event::TimelineChanged {
+                timeline_id: id.clone(),
+                diffs: normalised.diffs,
+            };
+            if events.send(event).await.is_err() {
+                return;
+            }
+        }
+    }))
+}
+
+async fn run_pagination(
+    mut requests: mpsc::Receiver<PaginationRequest>,
+    timeline: Arc<Timeline>,
+    events: EventSender,
+    timeline_id: TimelineId,
+) {
+    while let Some(PaginationRequest { limit, reply }) = requests.recv().await {
+        let history = |state| Event::HistoryChanged {
+            timeline_id: timeline_id.clone(),
+            state,
+        };
+        if events.send(history(HistoryState::Loading)).await.is_err() {
+            return;
+        }
+        let result = timeline
+            .paginate_backwards(limit.max(1))
+            .await
+            .map_err(timeline_error);
+        let state = match &result {
+            Ok(true) => HistoryState::StartReached,
+            Ok(false) => HistoryState::Idle,
+            Err(error) => HistoryState::Failed(error.to_string()),
+        };
+        let _ = events.send(history(state)).await;
+        if let Some(reply) = reply {
+            reply.done(result.map(drop));
+        }
+    }
+}
+
+fn message_content(
+    content: RichText,
+    mentions: MessageMentions,
+    emote: bool,
+) -> RoomMessageEventContentWithoutRelation {
+    let content = match content.formatted_body {
+        Some(formatted_body) if emote => {
+            RoomMessageEventContentWithoutRelation::emote_html(content.body, formatted_body)
+        }
+        Some(formatted_body) => {
+            RoomMessageEventContentWithoutRelation::text_html(content.body, formatted_body)
+        }
+        None if emote => RoomMessageEventContentWithoutRelation::emote_plain(content.body),
+        None => RoomMessageEventContentWithoutRelation::text_plain(content.body),
+    };
+    let content = content.add_mentions(Mentions::with_user_ids(mentions.user_ids));
+    if mentions.room {
+        content.add_mentions(Mentions::with_room_mention())
+    } else {
+        content
+    }
+}
+
+pub(super) fn timeline_error(source: matrix_sdk_ui::timeline::Error) -> Error {
+    Error::with_source(ErrorKind::Timeline, "timeline operation failed", source)
+}

Added file: src/engine/watchers.rs+268 additions@@ -0,0 +1,268 @@
+use std::{sync::Arc, time::Duration};
+
+use futures_util::StreamExt;
+use matrix_sdk::{
+    Client, Room, SessionChange,
+    ruma::events::{AnyMessageLikeEventContent, room::message::MessageType},
+    send_queue::{LocalEchoContent, RoomSendQueueUpdate},
+};
+use matrix_sdk_ui::sync_service::{State as SyncState, SyncService};
+use tokio::{
+    sync::{Notify, broadcast::error::RecvError, watch},
+    task::JoinSet,
+};
+
+use crate::{
+    ConnectionState, Event, encryption::encryption_state, error::classify_sdk_error,
+    transport::EventSender,
+};
+
+const SYNC_RESTART_MIN: Duration = Duration::from_secs(1);
+const SYNC_RESTART_MAX: Duration = Duration::from_secs(60);
+const SEND_QUEUE_RETRY: Duration = Duration::from_secs(5);
+
+pub(super) async fn session(
+    mut changes: tokio::sync::broadcast::Receiver<SessionChange>,
+    events: EventSender,
+    stop: Arc<Notify>,
+) {
+    loop {
+        let event = match changes.recv().await {
+            Ok(SessionChange::TokensRefreshed) => Event::SessionTokensChanged,
+            Ok(SessionChange::UnknownToken(data)) => {
+                let _ = events
+                    .send(Event::SessionAccessRejected {
+                        soft_logout: data.soft_logout,
+                    })
+                    .await;
+                stop.notify_one();
+                return;
+            }
+            // a missed refresh costs one needless save, a missed rejection comes round again
+            Err(RecvError::Lagged(_)) => Event::SessionTokensChanged,
+            Err(RecvError::Closed) => return,
+        };
+        if events.send(event).await.is_err() {
+            return;
+        }
+    }
+}
+
+/// `states` must be taken before sync starts, a late subscriber never hears the transition it missed
+pub(super) async fn connection(
+    mut states: impl futures_util::Stream<Item = SyncState> + Unpin,
+    sync: Arc<SyncService>,
+    client: Client,
+    events: EventSender,
+    connection: watch::Sender<ConnectionState>,
+) {
+    let mut backoff = SYNC_RESTART_MIN;
+    while let Some(state) = states.next().await {
+        let (state, restart) = match state {
+            SyncState::Idle => (ConnectionState::Idle, false),
+            SyncState::Running => {
+                backoff = SYNC_RESTART_MIN;
+                // the sdk parks a room queue on any send error and never unparks it
+                client.send_queue().set_enabled(true).await;
+                (ConnectionState::Online, false)
+            }
+            SyncState::Offline => (ConnectionState::Offline, false),
+            SyncState::Terminated => (ConnectionState::Offline, true),
+            SyncState::Error(error) => {
+                tracing::warn!(%error, "sync service reported an error");
+                (ConnectionState::Offline, true)
+            }
+        };
+        if *connection.borrow() != state {
+            connection.send_replace(state);
+            if events.send(Event::ConnectionChanged(state)).await.is_err() {
+                return;
+            }
+        }
+        if restart {
+            tokio::time::sleep(backoff).await;
+            backoff = (backoff * 2).min(SYNC_RESTART_MAX);
+            sync.start().await;
+        }
+    }
+}
+
+/// a recoverable failure while we're online is a hiccup, so give the room another go
+pub(super) async fn send_queue_errors(
+    client: Client,
+    mut errors: tokio::sync::broadcast::Receiver<matrix_sdk::send_queue::SendQueueRoomError>,
+    online: watch::Receiver<ConnectionState>,
+) {
+    let mut retries = JoinSet::new();
+    loop {
+        let error = tokio::select! {
+            error = errors.recv() => error,
+            Some(_) = retries.join_next(), if !retries.is_empty() => continue,
+        };
+        match error {
+            Ok(error) if error.is_recoverable => {
+                let client = client.clone();
+                let online = online.clone();
+                retries.spawn(async move {
+                    tokio::time::sleep(SEND_QUEUE_RETRY).await;
+                    if *online.borrow() == ConnectionState::Online
+                        && let Some(room) = client.get_room(&error.room_id)
+                    {
+                        room.send_queue().set_enabled(true);
+                    }
+                });
+            }
+            Ok(_) | Err(RecvError::Lagged(_)) => {}
+            Err(RecvError::Closed) => return,
+        }
+    }
+}
+
+/// upload progress only goes out on the room's own channel, never the client-wide one
+pub(super) async fn room_uploads(room: Room, events: EventSender, ready: watch::Sender<bool>) {
+    let room_id = room.room_id().to_owned();
+    let mut updates = match room.send_queue().subscribe().await {
+        Ok((_, updates)) => updates,
+        Err(error) => {
+            tracing::warn!(%room_id, %error, "reading the media send queue failed");
+            return;
+        }
+    };
+    ready.send_replace(true);
+    loop {
+        let update = match updates.recv().await {
+            Ok(update) => update,
+            Err(RecvError::Lagged(skipped)) => {
+                tracing::warn!(%room_id, skipped, "upload watcher lagged");
+                continue;
+            }
+            Err(RecvError::Closed) => return,
+        };
+        let event = match update {
+            RoomSendQueueUpdate::MediaUpload {
+                related_to,
+                file,
+                progress,
+                ..
+            } => Event::MediaUploadProgress {
+                room_id: room_id.clone(),
+                transaction_id: related_to,
+                uploaded_bytes: progress.current as u64,
+                total_bytes: progress.total as u64,
+                complete: file.is_some() && progress.current == progress.total,
+            },
+            RoomSendQueueUpdate::SendError {
+                transaction_id,
+                error,
+                is_recoverable,
+            } => {
+                let is_attachment = room
+                    .send_queue()
+                    .subscribe()
+                    .await
+                    .is_ok_and(|(echoes, _)| {
+                        echoes.iter().any(|echo| {
+                            echo.transaction_id == transaction_id
+                                && is_attachment_echo(&echo.content)
+                        })
+                    });
+                if !is_attachment {
+                    continue;
+                }
+                Event::MediaUploadFailed {
+                    room_id: room_id.clone(),
+                    transaction_id,
+                    kind: classify_sdk_error(&error),
+                    recoverable: is_recoverable,
+                }
+            }
+            _ => continue,
+        };
+        if events.send(event).await.is_err() {
+            return;
+        }
+    }
+}
+
+fn is_attachment_echo(content: &LocalEchoContent) -> bool {
+    let LocalEchoContent::Event {
+        serialized_event, ..
+    } = content
+    else {
+        return false;
+    };
+    matches!(
+        serialized_event.deserialize(),
+        Ok(AnyMessageLikeEventContent::RoomMessage(content))
+            if matches!(
+                content.msgtype,
+                MessageType::Audio(_) | MessageType::File(_) | MessageType::Image(_) | MessageType::Video(_)
+            )
+    )
+}
+
+pub(super) async fn encryption(client: Client, events: EventSender) {
+    let Some(device_id) = client.device_id().map(ToOwned::to_owned) else {
+        tracing::warn!("encryption watcher stopped because the client has no device id");
+        return;
+    };
+    let recovery = client.encryption().recovery();
+    let backups = client.encryption().backups();
+    let mut recovery_stream = recovery.state_stream();
+    let mut backup_stream = backups.state_stream();
+    let mut verification_stream = client.encryption().verification_state();
+    let mut recovery_state = recovery.state();
+    let mut backup_state = backups.state();
+    let mut verification_state = verification_stream.get();
+    loop {
+        let state = encryption_state(
+            device_id.clone(),
+            recovery_state,
+            verification_state,
+            backup_state,
+        );
+        if events.send(Event::EncryptionChanged(state)).await.is_err() {
+            return;
+        }
+        tokio::select! {
+            Some(update) = recovery_stream.next() => recovery_state = update,
+            Some(update) = verification_stream.next() => verification_state = update,
+            Some(update) = backup_stream.next() => {
+                backup_state = update.unwrap_or_else(|_| backups.state());
+            }
+            else => return,
+        }
+    }
+}
+
+pub(super) async fn rooms(client: Client, events: EventSender) {
+    let (_, mut rooms) = client.rooms_stream();
+    let mut info = client.room_info_notable_update_receiver();
+    loop {
+        if events.send(Event::RoomsChanged).await.is_err() {
+            return;
+        }
+        tokio::select! {
+            update = rooms.next() => if update.is_none() { return },
+            update = info.recv() => if matches!(update, Err(RecvError::Closed)) { return },
+        }
+        // a sync touching fifty rooms is one invalidation, not fifty
+        while let Ok(_) | Err(tokio::sync::broadcast::error::TryRecvError::Lagged(_)) =
+            info.try_recv()
+        {}
+    }
+}
+
+pub(super) async fn notification_settings(client: Client, events: EventSender) {
+    let settings = client.notification_settings().await;
+    let mut changes = settings.subscribe_to_changes();
+    while let Ok(()) | Err(RecvError::Lagged(_)) = changes.recv().await {
+        if events
+            .send(Event::NotificationSettingsChanged)
+            .await
+            .is_err()
+        {
+            return;
+        }
+    }
+}

Modified file: src/error.rs+113 additions−44 deletions@@ -1,4 +1,4 @@
-use thiserror::Error;
+use std::sync::Arc;
 
 use matrix_sdk::{
     HttpError, RefreshTokenError,
@@ -12,36 +12,98 @@ use matrix_sdk::{
         secret_storage::{ImportError, SecretStorageError},
     },
 };
+#[cfg(feature = "serde")]
+use serde::{Deserialize, Serialize};
 
-use crate::CommandErrorKind;
+use crate::InteractiveAuthChallenge;
 
-#[derive(Debug, Error)]
+/// the one thing that goes wrong, for commands and queries alike. match on `kind`, show `message`
+#[derive(Clone, Debug, thiserror::Error)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[error("{message}")]
-pub(crate) struct CommandError {
-    pub(crate) kind: CommandErrorKind,
-    message: String,
+#[non_exhaustive]
+pub struct Error {
+    pub kind: ErrorKind,
+    pub message: String,
+    /// set when the server wants interactive auth before it'll do the thing
+    pub challenge: Option<Box<InteractiveAuthChallenge>>,
     #[source]
-    source: Option<Box<dyn std::error::Error + Send + Sync>>,
+    #[cfg_attr(feature = "serde", serde(skip))]
+    source: Option<Arc<dyn std::error::Error + Send + Sync>>,
 }
 
-impl CommandError {
-    pub(crate) fn new(kind: CommandErrorKind, message: impl Into<String>) -> Self {
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
+pub enum ErrorKind {
+    /// the engine stopped, or the task doing the work died, before answering
+    Interrupted,
+    Unauthenticated,
+    InteractiveAuthRequired,
+    Invalid,
+    RoomUnknown,
+    RoomNotOpen,
+    TimelineNotOpen,
+    RoomBusy,
+    QueueFull,
+    EmptyBody,
+    MediaUnknown,
+    MediaTooLarge,
+    MediaUnavailable,
+    VerificationInactive,
+    VerificationUnsupported,
+    NoCrossSigningIdentity,
+    RecoveryRejected,
+    Network,
+    Server,
+    Store,
+    Timeline,
+    Encryption,
+    Other,
+}
+
+impl Error {
+    pub(crate) fn new(kind: ErrorKind, message: impl Into<String>) -> Self {
         Self {
             kind,
             message: message.into(),
+            challenge: None,
             source: None,
         }
     }
 
     pub(crate) fn with_source(
-        kind: CommandErrorKind,
+        kind: ErrorKind,
         message: impl Into<String>,
         source: impl std::error::Error + Send + Sync + 'static,
     ) -> Self {
         Self {
-            kind,
-            message: message.into(),
-            source: Some(Box::new(source)),
+            source: Some(Arc::new(source)),
+            ..Self::new(kind, message)
+        }
+    }
+
+    pub(crate) fn interrupted() -> Self {
+        Self::new(
+            ErrorKind::Interrupted,
+            "the engine stopped before the operation finished",
+        )
+    }
+
+    pub(crate) fn room_unknown() -> Self {
+        Self::new(
+            ErrorKind::RoomUnknown,
+            "room is not available in the local store",
+        )
+    }
+
+    pub(crate) fn interactive_auth(challenge: InteractiveAuthChallenge) -> Self {
+        Self {
+            challenge: Some(Box::new(challenge)),
+            ..Self::new(
+                ErrorKind::InteractiveAuthRequired,
+                "interactive authentication is required",
+            )
         }
     }
 
@@ -52,6 +114,7 @@ impl CommandError {
     pub(crate) fn from_http(message: impl Into<String>, source: HttpError) -> Self {
         Self::with_source(classify_http_error(&source), message, source)
     }
+
     pub(crate) fn from_refresh_token(
         message: impl Into<String>,
         source: RefreshTokenError,
@@ -68,21 +131,21 @@ impl CommandError {
             RecoveryError::SecretStorage(SecretStorageError::ImportError { error, .. }) => {
                 match error {
                     ImportError::Sdk(source) => classify_sdk_error(source),
-                    _ => CommandErrorKind::RecoveryRejected,
+                    _ => ErrorKind::RecoveryRejected,
                 }
             }
             RecoveryError::SecretStorage(SecretStorageError::Verification(source)) => {
                 match source {
                     ManualVerifyError::Http(source) => classify_http_error(source),
-                    _ => CommandErrorKind::RecoveryRejected,
+                    _ => ErrorKind::RecoveryRejected,
                 }
             }
             RecoveryError::SecretStorage(SecretStorageError::SecretStorageKey(_)) => {
-                CommandErrorKind::RecoveryRejected
+                ErrorKind::RecoveryRejected
             }
-            RecoveryError::SecretStorage(SecretStorageError::Storage(_)) => CommandErrorKind::Store,
+            RecoveryError::SecretStorage(SecretStorageError::Storage(_)) => ErrorKind::Store,
             RecoveryError::BackupExistsOnServer | RecoveryError::SecretStorage(_) => {
-                CommandErrorKind::RecoveryRejected
+                ErrorKind::RecoveryRejected
             }
         };
         Self::with_source(kind, message, source)
@@ -94,77 +157,83 @@ impl CommandError {
     ) -> Self {
         let kind = match &source {
             RequestVerificationError::Sdk(source) => classify_sdk_error(source),
-            RequestVerificationError::RoomCreation(_) => CommandErrorKind::Encryption,
+            RequestVerificationError::RoomCreation(_) => ErrorKind::Encryption,
         };
         Self::with_source(kind, message, source)
     }
 }
 
-pub(crate) fn classify_sdk_error(source: &matrix_sdk::Error) -> CommandErrorKind {
+impl PartialEq for Error {
+    fn eq(&self, other: &Self) -> bool {
+        self.kind == other.kind
+            && self.message == other.message
+            && self.challenge == other.challenge
+    }
+}
+
+pub(crate) fn classify_sdk_error(source: &matrix_sdk::Error) -> ErrorKind {
     match source {
         matrix_sdk::Error::Http(source) => classify_http_error(source),
         matrix_sdk::Error::OAuth(source) => classify_oauth_error(source),
-        matrix_sdk::Error::AuthenticationRequired => CommandErrorKind::Unauthenticated,
+        matrix_sdk::Error::AuthenticationRequired => ErrorKind::Unauthenticated,
         matrix_sdk::Error::BadCryptoStoreState
         | matrix_sdk::Error::CryptoStoreError(_)
         | matrix_sdk::Error::CrossProcessLockError(_)
         | matrix_sdk::Error::StateStore(_)
         | matrix_sdk::Error::EventCacheStore(_)
-        | matrix_sdk::Error::MediaStore(_) => CommandErrorKind::Store,
+        | matrix_sdk::Error::MediaStore(_) => ErrorKind::Store,
         matrix_sdk::Error::NoOlmMachine
         | matrix_sdk::Error::OlmError(_)
         | matrix_sdk::Error::MegolmError(_)
-        | matrix_sdk::Error::DecryptorError(_) => CommandErrorKind::Encryption,
-        matrix_sdk::Error::Media(_) => CommandErrorKind::MediaUnavailable,
-        matrix_sdk::Error::Timeout => CommandErrorKind::Network,
-        _ => CommandErrorKind::Other,
+        | matrix_sdk::Error::DecryptorError(_) => ErrorKind::Encryption,
+        matrix_sdk::Error::Media(_) => ErrorKind::MediaUnavailable,
+        matrix_sdk::Error::Timeout => ErrorKind::Network,
+        _ => ErrorKind::Other,
     }
 }
 
-fn classify_http_error(source: &HttpError) -> CommandErrorKind {
+fn classify_http_error(source: &HttpError) -> ErrorKind {
     match source {
-        HttpError::Reqwest(_) => CommandErrorKind::Network,
-        HttpError::Api(_) => CommandErrorKind::Server,
+        HttpError::Reqwest(_) => ErrorKind::Network,
+        HttpError::Api(_) => ErrorKind::Server,
         HttpError::RefreshToken(source) => classify_refresh_token_error(source),
         HttpError::Cached(source) => classify_http_error(source),
-        _ => CommandErrorKind::Other,
+        _ => ErrorKind::Other,
     }
 }
 
-fn classify_refresh_token_error(source: &RefreshTokenError) -> CommandErrorKind {
+fn classify_refresh_token_error(source: &RefreshTokenError) -> ErrorKind {
     match source {
-        RefreshTokenError::RefreshTokenRequired => CommandErrorKind::Unauthenticated,
+        RefreshTokenError::RefreshTokenRequired => ErrorKind::Unauthenticated,
         RefreshTokenError::MatrixAuth(source) => classify_http_error(source),
         RefreshTokenError::OAuth(source) => classify_oauth_error(source),
     }
 }
 
-fn classify_oauth_error(source: &OAuthError) -> CommandErrorKind {
+fn classify_oauth_error(source: &OAuthError) -> ErrorKind {
     let classify_token_request_error = |source: &_| match source {
-        RequestTokenError::Request(_) => CommandErrorKind::Network,
-        RequestTokenError::ServerResponse(_) => CommandErrorKind::Unauthenticated,
-        _ => CommandErrorKind::Other,
+        RequestTokenError::Request(_) => ErrorKind::Network,
+        RequestTokenError::ServerResponse(_) => ErrorKind::Unauthenticated,
+        _ => ErrorKind::Other,
     };
     match source {
         OAuthError::Discovery(source) => match source {
             OAuthDiscoveryError::Http(source) => classify_http_error(source),
             OAuthDiscoveryError::Oidc(source) => classify_token_request_error(source),
-            _ => CommandErrorKind::Unauthenticated,
+            _ => ErrorKind::Unauthenticated,
         },
         OAuthError::RefreshToken(source) => classify_token_request_error(source),
         OAuthError::AuthorizationCode(OAuthAuthorizationCodeError::RequestToken(source)) => {
             classify_token_request_error(source)
         }
-        OAuthError::AuthorizationCode(_) => CommandErrorKind::Unauthenticated,
+        OAuthError::AuthorizationCode(_) => ErrorKind::Unauthenticated,
         OAuthError::Logout(source) => match source {
-            OAuthTokenRevocationError::Revoke(RequestTokenError::Request(_)) => {
-                CommandErrorKind::Network
-            }
+            OAuthTokenRevocationError::Revoke(RequestTokenError::Request(_)) => ErrorKind::Network,
             OAuthTokenRevocationError::Revoke(RequestTokenError::ServerResponse(_)) => {
-                CommandErrorKind::Unauthenticated
+                ErrorKind::Unauthenticated
             }
-            _ => CommandErrorKind::Other,
+            _ => ErrorKind::Other,
         },
-        _ => CommandErrorKind::Unauthenticated,
+        _ => ErrorKind::Unauthenticated,
     }
 }

Modified file: src/lib.rs+12 additions−13 deletions@@ -19,23 +19,22 @@ pub use account::{
 };
 
 pub use engine::{Engine, EngineConfig, EngineError};
+pub use error::{Error, ErrorKind};
 pub use model::{
-    AccountCommand, AttachmentUpload, Command, CommandErrorKind, CommandFailure, CommandId,
-    CommandKind, ConnectionState, CreateRoomOptions, EncryptionCommand, EncryptionState,
-    EngineErrorKind, EngineFailure, Event, HistoryState, KeyBackupState, LifecycleCommand,
-    MediaCommand, MediaDescriptor, MediaId, MediaKind, MediaSize, MemberFilter, MemberMembership,
-    MemberSummary, MessageContent, MessageEditContent, MessageMentions, NotificationCommand,
-    OwnDevice, PowerLevelChanges, PushNotification, PushNotificationEvent, PushNotificationRoom,
-    PushNotificationSender, PushNotificationStatus, Reaction, RecoveryState, ReplyReference,
-    RichText, RoomCategory, RoomCommand, RoomListFilter, RoomMembership, RoomNotificationMode,
+    AccountCommand, AttachmentUpload, Command, CommandOutput, ConnectionState, CreateRoomOptions,
+    EncryptionCommand, EncryptionState, EngineErrorKind, EngineFailure, Event, HistoryState,
+    KeyBackupState, LatestEvent, LifecycleCommand, Media, MediaCommand, MediaDescriptor, MediaId,
+    MediaKind, MediaSize, MemberFilter, MemberMembership, MemberSummary, MessageContent,
+    MessageEditContent, MessageMentions, NotificationCommand, OwnDevice, PowerLevelChanges,
+    Profile, PushNotification, PushNotificationEvent, PushNotificationRoom, PushNotificationSender,
+    PushNotificationStatus, Reaction, RecoveryState, ReplyReference, RichText, RoomCategory,
+    RoomCommand, RoomHero, RoomListFilter, RoomMatcher, RoomMembership, RoomNotificationMode,
     RoomNotificationSettings, RoomPowerLevels, RoomPreset, RoomSummary, RoomVisibility, SendState,
-    ThreadSummary, TimelineCommand, TimelineDiff, TimelineDiffError, TimelineId, TimelineItem,
-    TimelineItemId, TimelineMessage, TypingState, UploadDetails, UploadThumbnail,
+    SpaceChild, ThreadSummary, TimelineCommand, TimelineDiff, TimelineDiffError, TimelineId,
+    TimelineItem, TimelineItemId, TimelineMessage, TypingState, UploadDetails, UploadThumbnail,
     VerificationAction, VerificationFailure, VerificationState, VerificationTarget,
 };
-pub use transport::{
-    ClientHandle, ClientQueryError, CommandResultError, EventStream, SendCommandError,
-};
+pub use transport::{ClientHandle, EventStream, Pending, SpaceHierarchy};
 pub use uiaa::{
     InteractiveAuth, InteractiveAuthChallenge, InteractiveAuthFailure, InteractiveAuthFlow,
     InteractiveAuthOutcome,

Modified file: src/model.rs+209 additions−127 deletions@@ -3,13 +3,19 @@ use std::{fmt, sync::Arc};
 use ruma::{
     OwnedDeviceId, OwnedEventId, OwnedMxcUri, OwnedRoomAliasId, OwnedRoomId, OwnedRoomOrAliasId,
     OwnedServerName, OwnedTransactionId, OwnedUserId,
-    events::{AnySyncTimelineEvent, room::member::StrippedRoomMemberEvent},
+    events::{
+        AnyGlobalAccountDataEventContent, AnyRoomAccountDataEventContent, AnySyncTimelineEvent,
+        GlobalAccountDataEventType, RoomAccountDataEventType,
+        room::member::StrippedRoomMemberEvent,
+    },
     serde::Raw,
 };
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Eq, PartialEq)]
+/// every command answers exactly once through `ClientHandle::send` or `execute`.
+/// the event stream only ever carries state
+#[derive(Debug)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[non_exhaustive]
 pub enum Command {
@@ -22,11 +28,22 @@ pub enum Command {
     Lifecycle(LifecycleCommand),
 }
 
-#[derive(Debug, Eq, PartialEq)]
+#[derive(Debug)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[non_exhaustive]
 pub enum AccountCommand {
     Logout,
+    SetAccountData {
+        event_type: GlobalAccountDataEventType,
+        content: Raw<AnyGlobalAccountDataEventContent>,
+    },
+    SetDisplayName(Option<String>),
+    SetAvatar(Option<OwnedMxcUri>),
+    /// uploads the image and points the profile at it, same byte cap as any upload
+    UploadAvatar {
+        mimetype: String,
+        bytes: Vec<u8>,
+    },
     RenameDevice {
         device_id: OwnedDeviceId,
         display_name: String,
@@ -37,10 +54,11 @@ pub enum AccountCommand {
     },
 }
 
-#[derive(Clone, Debug, Eq, PartialEq)]
+#[derive(Clone, Debug)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[non_exhaustive]
 pub enum RoomCommand {
+    /// the snapshot turns up as `Event::TimelineReset`. opening an open room sends a fresh one
     Open(OwnedRoomId),
     Close(OwnedRoomId),
     Join {
@@ -94,10 +112,16 @@ pub enum RoomCommand {
         room_id: OwnedRoomId,
         typing: bool,
     },
+    SetAccountData {
+        room_id: OwnedRoomId,
+        event_type: RoomAccountDataEventType,
+        content: Raw<AnyRoomAccountDataEventContent>,
+    },
 }
 
 #[derive(Clone, Debug, Default, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub struct CreateRoomOptions {
     pub name: Option<String>,
     pub topic: Option<String>,
@@ -108,6 +132,50 @@ pub struct CreateRoomOptions {
     pub preset: Option<RoomPreset>,
 }
 
+impl CreateRoomOptions {
+    #[must_use]
+    pub fn with_name(mut self, name: impl Into<String>) -> Self {
+        self.name = Some(name.into());
+        self
+    }
+
+    #[must_use]
+    pub fn with_topic(mut self, topic: impl Into<String>) -> Self {
+        self.topic = Some(topic.into());
+        self
+    }
+
+    #[must_use]
+    pub fn with_alias_localpart(mut self, localpart: impl Into<String>) -> Self {
+        self.alias_localpart = Some(localpart.into());
+        self
+    }
+
+    #[must_use]
+    pub fn with_invite(mut self, invite: impl IntoIterator<Item = OwnedUserId>) -> Self {
+        self.invite = invite.into_iter().collect();
+        self
+    }
+
+    #[must_use]
+    pub const fn with_direct(mut self, direct: bool) -> Self {
+        self.direct = direct;
+        self
+    }
+
+    #[must_use]
+    pub const fn with_visibility(mut self, visibility: RoomVisibility) -> Self {
+        self.visibility = visibility;
+        self
+    }
+
+    #[must_use]
+    pub const fn with_preset(mut self, preset: RoomPreset) -> Self {
+        self.preset = Some(preset);
+        self
+    }
+}
+
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum RoomVisibility {
@@ -247,18 +315,8 @@ impl From<OwnedRoomId> for TimelineId {
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[non_exhaustive]
 pub enum MediaCommand {
-    Fetch {
-        id: MediaId,
-        size: MediaSize,
-    },
-    Upload {
-        timeline_id: TimelineId,
-        filename: String,
-        mimetype: String,
-        bytes: Vec<u8>,
-        caption: Option<String>,
-    },
-    UploadAttachment(AttachmentUpload),
+    /// succeeds once the send queue has it. progress and failure arrive as events
+    Upload(AttachmentUpload),
 }
 
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -320,6 +378,7 @@ pub enum UploadDetails {
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub struct UploadThumbnail {
     pub bytes: Vec<u8>,
     pub mimetype: String,
@@ -327,6 +386,18 @@ pub struct UploadThumbnail {
     pub height: u32,
 }
 
+impl UploadThumbnail {
+    #[must_use]
+    pub fn new(bytes: Vec<u8>, mimetype: impl Into<String>, width: u32, height: u32) -> Self {
+        Self {
+            bytes,
+            mimetype: mimetype.into(),
+            width,
+            height,
+        }
+    }
+}
+
 #[derive(Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[non_exhaustive]
@@ -388,31 +459,12 @@ pub enum LifecycleCommand {
     Shutdown,
 }
 
-impl Command {
-    #[must_use]
-    pub const fn kind(&self) -> CommandKind {
-        match self {
-            Self::Account(_) => CommandKind::Account,
-            Self::Room(_) => CommandKind::Room,
-            Self::Timeline(_) => CommandKind::Timeline,
-            Self::Media(_) => CommandKind::Media,
-            Self::Encryption(_) => CommandKind::Encryption,
-            Self::Notification(_) => CommandKind::Notification,
-            Self::Lifecycle(_) => CommandKind::Lifecycle,
-        }
-    }
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
-pub enum CommandKind {
-    Account,
-    Room,
-    Timeline,
-    Media,
-    Encryption,
-    Notification,
-    Lifecycle,
+#[non_exhaustive]
+pub enum CommandOutput {
+    Done,
+    Room(OwnedRoomId),
 }
 
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -590,14 +642,8 @@ pub enum Event {
     },
     NotificationSettingsChanged,
     VerificationTargetChanged(VerificationTarget),
-    InteractiveAuthRequired {
-        id: CommandId,
-        command: CommandKind,
-        challenge: crate::InteractiveAuthChallenge,
-    },
     RoomsChanged,
-    /// Authoritative snapshot on open or resync. A resync reset precedes the
-    /// corresponding terminal command event on this stream.
+    /// replaces whatever you had for this timeline. every diff after it applies to it
     TimelineReset {
         timeline_id: TimelineId,
         items: Vec<TimelineItem>,
@@ -611,12 +657,6 @@ pub enum Event {
         state: HistoryState,
     },
     TypingChanged(TypingState),
-    MediaReady {
-        media_id: MediaId,
-        size: MediaSize,
-        bytes: Arc<[u8]>,
-        mimetype: String,
-    },
     MediaUploadProgress {
         room_id: OwnedRoomId,
         transaction_id: OwnedTransactionId,
@@ -627,24 +667,11 @@ pub enum Event {
     MediaUploadFailed {
         room_id: OwnedRoomId,
         transaction_id: OwnedTransactionId,
-        kind: CommandErrorKind,
+        kind: crate::ErrorKind,
         recoverable: bool,
     },
     EncryptionChanged(EncryptionState),
     VerificationChanged(VerificationState),
-    /// Terminal command success. For sends, this means the SDK send queue
-    /// accepted the item; network delivery is reflected by its send state.
-    CommandSucceeded {
-        id: CommandId,
-        command: CommandKind,
-    },
-    CommandSucceededWithRoom {
-        id: CommandId,
-        command: CommandKind,
-        room_id: OwnedRoomId,
-    },
-    /// Terminal failure correlated by `CommandFailure::id`.
-    CommandFailed(CommandFailure),
     /// logout went through and the engine stops. delete the record and the store
     LoggedOut,
     Failed(EngineFailure),
@@ -653,23 +680,9 @@ pub enum Event {
     Stopped,
 }
 
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
-#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
-pub struct CommandId(u64);
-
-impl CommandId {
-    pub(crate) const fn new(value: u64) -> Self {
-        Self(value)
-    }
-
-    #[must_use]
-    pub const fn get(self) -> u64 {
-        self.0
-    }
-}
-
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub enum ConnectionState {
     Idle,
     Connecting,
@@ -694,12 +707,76 @@ pub struct RoomSummary {
     pub low_priority: bool,
     pub avatar: Option<OwnedMxcUri>,
     pub latest_event_timestamp_ms: Option<u64>,
+    pub latest_event: Option<LatestEvent>,
     pub notification_mode: Option<RoomNotificationMode>,
     pub notification_mode_custom: bool,
+    pub topic: Option<String>,
+    pub canonical_alias: Option<OwnedRoomAliasId>,
+    pub joined_members: u64,
+    pub invited_members: u64,
+    /// who a nameless room gets named after
+    pub heroes: Vec<RoomHero>,
+    /// set once the room has been upgraded, this is where everyone went
+    pub successor: Option<OwnedRoomId>,
+    pub inviter: Option<OwnedUserId>,
+    /// joined spaces that list this room as a child
+    pub parent_spaces: Vec<OwnedRoomId>,
+    /// for a space, the children it lists, joined or not
+    pub children: Vec<OwnedRoomId>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
+pub struct RoomHero {
+    pub user_id: OwnedUserId,
+    pub display_name: Option<String>,
+    pub avatar: Option<OwnedMxcUri>,
+}
+
+/// enough for a room list preview line. `body` is empty for anything that isn't a plain message
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
+pub struct LatestEvent {
+    pub sender: Option<OwnedUserId>,
+    pub body: Option<String>,
+    pub timestamp_ms: Option<u64>,
+    pub send_state: SendState,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
+pub struct Profile {
+    pub user_id: OwnedUserId,
+    pub display_name: Option<String>,
+    pub avatar: Option<OwnedMxcUri>,
+}
+
+/// one room in a space's hierarchy, as the server describes it, which may be a room you're not in
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
+pub struct SpaceChild {
+    pub room_id: OwnedRoomId,
+    pub name: String,
+    pub topic: Option<String>,
+    pub avatar: Option<OwnedMxcUri>,
+    pub canonical_alias: Option<OwnedRoomAliasId>,
+    pub joined_members: u64,
+    pub space: bool,
+    pub children_count: u64,
+    pub membership: Option<RoomMembership>,
+    pub via: Vec<OwnedServerName>,
+    pub suggested: bool,
+    pub world_readable: Option<bool>,
+    pub guest_can_join: bool,
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub enum RoomNotificationMode {
     AllMessages,
     MentionsAndKeywordsOnly,
@@ -810,6 +887,7 @@ pub struct PowerLevelChanges {
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub enum RoomMembership {
     Joined,
     Invited,
@@ -862,21 +940,44 @@ impl RoomListFilter {
 
     #[must_use]
     pub fn matches(&self, room: &RoomSummary) -> bool {
-        self.membership
+        self.matcher().matches(room)
+    }
+
+    /// lowercases the search once, for filtering a whole list
+    #[must_use]
+    pub fn matcher(&self) -> RoomMatcher<'_> {
+        RoomMatcher {
+            filter: self,
+            search: self.search.as_deref().map(str::to_lowercase),
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct RoomMatcher<'a> {
+    filter: &'a RoomListFilter,
+    search: Option<String>,
+}
+
+impl RoomMatcher<'_> {
+    #[must_use]
+    pub fn matches(&self, room: &RoomSummary) -> bool {
+        let filter = self.filter;
+        filter
+            .membership
             .is_none_or(|membership| room.membership == membership)
-            && self.category.is_none_or(|category| match category {
+            && filter.category.is_none_or(|category| match category {
                 RoomCategory::People => room.direct && !room.space,
                 RoomCategory::Rooms => !room.direct && !room.space,
                 RoomCategory::Spaces => room.space,
             })
-            && self
+            && filter
                 .favourite
                 .is_none_or(|favourite| room.favourite == favourite)
-            && (!self.unread_only || room.unread_messages > 0 || room.unread_mentions > 0)
+            && (!filter.unread_only || room.unread_messages > 0 || room.unread_mentions > 0)
             && self.search.as_ref().is_none_or(|search| {
-                let search = search.to_lowercase();
-                room.name.to_lowercase().contains(&search)
-                    || room.room_id.as_str().to_lowercase().contains(&search)
+                room.name.to_lowercase().contains(search)
+                    || room.room_id.as_str().to_lowercase().contains(search)
             })
     }
 }
@@ -938,6 +1039,7 @@ pub struct OwnDevice {
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub enum TimelineItem {
     Message(Box<TimelineMessage>),
     DayDivider { timestamp_ms: u64 },
@@ -1161,6 +1263,7 @@ pub enum SendState {
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub struct ReplyReference {
     pub event_id: OwnedEventId,
     pub sender_id: Option<OwnedUserId>,
@@ -1215,8 +1318,19 @@ impl std::fmt::Display for MediaId {
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum MediaSize {
-    Thumbnail,
     Full,
+    /// a hint. an uploader's own thumbnail wins over the server resizing anything
+    Thumbnail {
+        width: u32,
+        height: u32,
+    },
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub struct Media {
+    pub bytes: Arc<[u8]>,
+    pub mimetype: String,
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -1232,6 +1346,7 @@ pub enum MediaKind {
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub struct TypingState {
     pub room_id: OwnedRoomId,
     pub users: Vec<OwnedUserId>,
@@ -1239,6 +1354,7 @@ pub struct TypingState {
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub enum HistoryState {
     Idle,
     Loading,
@@ -1258,6 +1374,7 @@ pub struct EncryptionState {
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub enum KeyBackupState {
     Unknown,
     Creating,
@@ -1270,6 +1387,7 @@ pub enum KeyBackupState {
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub enum RecoveryState {
     Unknown,
     Disabled,
@@ -1299,6 +1417,7 @@ pub enum VerificationTarget {
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[non_exhaustive]
 pub enum VerificationState {
     Waiting,
     Comparison {
@@ -1325,43 +1444,6 @@ pub enum VerificationFailure {
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[non_exhaustive]
-pub struct CommandFailure {
-    pub id: CommandId,
-    pub command: CommandKind,
-    pub kind: CommandErrorKind,
-    pub message: String,
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
-#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
-#[non_exhaustive]
-pub enum CommandErrorKind {
-    Unauthenticated,
-    RoomUnknown,
-    RoomNotOpen,
-    TimelineNotOpen,
-    RoomBusy,
-    QueueFull,
-    InteractiveAuthRequired,
-    EmptyBody,
-    MediaUnknown,
-    MediaTooLarge,
-    MediaUnavailable,
-    VerificationInactive,
-    VerificationUnsupported,
-    NoCrossSigningIdentity,
-    RecoveryRejected,
-    EventReceiverClosed,
-    Network,
-    Server,
-    Store,
-    Timeline,
-    Encryption,
-    Other,
-}
-
-#[derive(Clone, Debug, Eq, PartialEq)]
-#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct EngineFailure {
     pub kind: EngineErrorKind,
     pub message: String,

Modified file: src/normalise/mod.rs+1−1

@@ -6,5 +6,5 @@ mod timeline;

66 pub(crate) use media::{MediaRegistration, MediaScope};

77 pub(crate) use member::member_summary;

88 pub(crate) use room::notification_mode;

9-pub(crate) use room::room_summaries;

9+pub(crate) use room::{room_summaries, space_child};

1010 pub(crate) use timeline::{normalise_timeline, normalise_timeline_diffs};

Modified file: src/normalise/room.rs+157 additions−12 deletions@@ -1,11 +1,23 @@
 use futures_util::{StreamExt, stream};
-use matrix_sdk::{Client, Room, RoomState};
+use matrix_sdk::{
+    Client, Room, RoomState,
+    deserialized_responses::SyncOrStrippedState,
+    latest_events::LatestEventValue,
+    ruma::events::{
+        AnyMessageLikeEventContent, AnySyncMessageLikeEvent, AnySyncTimelineEvent, SyncStateEvent,
+        space::child::SpaceChildEventContent,
+    },
+};
+use matrix_sdk_ui::spaces::{SpaceRoom, SpaceService};
+use ruma::OwnedRoomId;
 
-use crate::{RoomMembership, RoomNotificationMode, RoomSummary};
+use crate::{
+    LatestEvent, RoomHero, RoomMembership, RoomNotificationMode, RoomSummary, SendState, SpaceChild,
+};
 
-pub(crate) async fn room_summaries(client: &Client) -> Vec<RoomSummary> {
+pub(crate) async fn room_summaries(client: &Client, spaces: &SpaceService) -> Vec<RoomSummary> {
     let mut summaries = stream::iter(client.rooms())
-        .map(|room| async move { room_summary(&room).await })
+        .map(|room| async move { room_summary(&room, spaces).await })
         .buffer_unordered(16)
         .collect::<Vec<_>>()
         .await;
@@ -19,7 +31,7 @@ pub(crate) async fn room_summaries(client: &Client) -> Vec<RoomSummary> {
     summaries
 }
 
-async fn room_summary(room: &Room) -> RoomSummary {
+async fn room_summary(room: &Room, spaces: &SpaceService) -> RoomSummary {
     let name = room
         .display_name()
         .await
@@ -30,16 +42,23 @@ async fn room_summary(room: &Room) -> RoomSummary {
         Some(mode) => Some(mode),
         None => room.notification_mode().await,
     };
+    let inviter = match room.state() {
+        RoomState::Invited => room
+            .invite_details()
+            .await
+            .ok()
+            .map(|invite| invite.inviter_id),
+        _ => None,
+    };
+    let children = if room.is_space() {
+        space_children(room).await
+    } else {
+        Vec::new()
+    };
     RoomSummary {
         room_id: room.room_id().to_owned(),
         name,
-        membership: match room.state() {
-            RoomState::Joined => RoomMembership::Joined,
-            RoomState::Invited => RoomMembership::Invited,
-            RoomState::Left => RoomMembership::Left,
-            RoomState::Knocked => RoomMembership::Knocked,
-            RoomState::Banned => RoomMembership::Banned,
-        },
+        membership: membership(room.state()),
         unread_messages: room.num_unread_messages(),
         unread_mentions: room.num_unread_mentions(),
         encrypted: room.encryption_state().is_encrypted(),
@@ -51,8 +70,134 @@ async fn room_summary(room: &Room) -> RoomSummary {
         latest_event_timestamp_ms: room
             .latest_event_timestamp()
             .map(|value| value.get().into()),
+        latest_event: latest_event(room),
         notification_mode: effective_notification_mode.map(notification_mode),
         notification_mode_custom: custom_notification_mode.is_some(),
+        topic: room.topic(),
+        canonical_alias: room.canonical_alias(),
+        joined_members: room.joined_members_count(),
+        invited_members: room.invited_members_count(),
+        heroes: room
+            .heroes()
+            .into_iter()
+            .map(|hero| RoomHero {
+                user_id: hero.user_id,
+                display_name: hero.display_name,
+                avatar: hero.avatar_url,
+            })
+            .collect(),
+        successor: room.successor_room().map(|successor| successor.room_id),
+        inviter,
+        parent_spaces: spaces
+            .joined_parents_of_child(room.room_id())
+            .await
+            .into_iter()
+            .map(|parent| parent.room_id)
+            .collect(),
+        children,
+    }
+}
+
+const fn membership(state: RoomState) -> RoomMembership {
+    match state {
+        RoomState::Joined => RoomMembership::Joined,
+        RoomState::Invited => RoomMembership::Invited,
+        RoomState::Left => RoomMembership::Left,
+        RoomState::Knocked => RoomMembership::Knocked,
+        RoomState::Banned => RoomMembership::Banned,
+    }
+}
+
+/// what the space itself lists, straight from local state. redacted children don't count
+async fn space_children(room: &Room) -> Vec<OwnedRoomId> {
+    let Ok(events) = room
+        .get_state_events_static::<SpaceChildEventContent>()
+        .await
+    else {
+        return Vec::new();
+    };
+    events
+        .into_iter()
+        .filter_map(|event| match event.deserialize().ok()? {
+            SyncOrStrippedState::Sync(SyncStateEvent::Original(event)) => Some(event.state_key),
+            SyncOrStrippedState::Stripped(event) => Some(event.state_key),
+            SyncOrStrippedState::Sync(SyncStateEvent::Redacted(_)) => None,
+        })
+        .collect()
+}
+
+fn latest_event(room: &Room) -> Option<LatestEvent> {
+    let (sender, body, timestamp, send_state) = match room.latest_event() {
+        LatestEventValue::None => return None,
+        LatestEventValue::Remote(event) => {
+            let body = match event.raw().deserialize() {
+                Ok(AnySyncTimelineEvent::MessageLike(AnySyncMessageLikeEvent::RoomMessage(
+                    message,
+                ))) => message
+                    .as_original()
+                    .map(|message| message.content.body().to_owned()),
+                _ => None,
+            };
+            (event.sender(), body, event.timestamp(), SendState::Sent)
+        }
+        LatestEventValue::RemoteInvite {
+            timestamp, inviter, ..
+        } => (inviter, None, Some(timestamp), SendState::Sent),
+        LatestEventValue::LocalIsSending(local) => local_event(room, &local, SendState::Sending),
+        LatestEventValue::LocalHasBeenSent { value, .. } => {
+            local_event(room, &value, SendState::Sent)
+        }
+        LatestEventValue::LocalCannotBeSent(local) => {
+            local_event(room, &local, SendState::Failed { retriable: true })
+        }
+    };
+    Some(LatestEvent {
+        sender,
+        body,
+        timestamp_ms: timestamp.map(|timestamp| timestamp.get().into()),
+        send_state,
+    })
+}
+
+type LatestParts = (
+    Option<ruma::OwnedUserId>,
+    Option<String>,
+    Option<ruma::MilliSecondsSinceUnixEpoch>,
+    SendState,
+);
+
+fn local_event(
+    room: &Room,
+    local: &matrix_sdk::latest_events::LocalLatestEventValue,
+    send_state: SendState,
+) -> LatestParts {
+    let body = match local.content.deserialize() {
+        Ok(AnyMessageLikeEventContent::RoomMessage(content)) => Some(content.body().to_owned()),
+        _ => None,
+    };
+    (
+        room.own_user_id().to_owned().into(),
+        body,
+        Some(local.timestamp),
+        send_state,
+    )
+}
+
+pub(crate) fn space_child(room: SpaceRoom) -> SpaceChild {
+    SpaceChild {
+        name: room.display_name,
+        room_id: room.room_id,
+        topic: room.topic,
+        avatar: room.avatar_url,
+        canonical_alias: room.canonical_alias,
+        joined_members: room.num_joined_members,
+        space: room.room_type == Some(ruma::room::RoomType::Space),
+        children_count: room.children_count,
+        membership: room.state.map(membership),
+        via: room.via,
+        suggested: room.suggested,
+        world_readable: room.world_readable,
+        guest_can_join: room.guest_can_join,
     }
 }
 

Modified file: src/transport.rs+519 additions−512 deletions@@ -1,10 +1,8 @@
-use std::sync::{
-    Arc,
-    atomic::{AtomicU64, Ordering},
-};
 use std::{
     fmt,
+    future::Future,
     pin::Pin,
+    sync::Arc,
     task::{Context, Poll},
 };
 
@@ -13,37 +11,44 @@ use matrix_sdk_ui::{
     notification_client::{
         NotificationClient, NotificationProcessSetup, NotificationStatus, RawNotificationEvent,
     },
+    spaces::{SpaceRoomList, SpaceService, room_list::SpaceRoomListPaginationState},
     sync_service::SyncService,
 };
 use ruma::{
-    EventId, RoomId,
+    EventId, MxcUri, OwnedDeviceId, OwnedEventId, OwnedMxcUri, OwnedRoomId, OwnedRoomOrAliasId,
+    OwnedServerName, OwnedTransactionId, OwnedUserId, RoomId, UserId,
     events::{
-        AnyGlobalAccountDataEventContent, AnyRoomAccountDataEvent, GlobalAccountDataEventType,
-        RoomAccountDataEventType,
+        AnyGlobalAccountDataEventContent, AnyRoomAccountDataEvent, AnyRoomAccountDataEventContent,
+        GlobalAccountDataEventType, RoomAccountDataEventType,
     },
     serde::Raw,
 };
-use thiserror::Error;
 use tokio::sync::{OnceCell, mpsc, oneshot, watch};
 
 use crate::{
-    AccountCommand, Command, CommandId, ConnectionState, EncryptionState, Event, InteractiveAuth,
-    InteractiveAuthOutcome, MemberFilter, MemberSummary, NotificationCommand, OwnDevice,
-    PowerLevelChanges, PushNotification, PushNotificationEvent, PushNotificationStatus,
-    RoomListFilter, RoomNotificationMode, RoomNotificationSettings, RoomPowerLevels, RoomSummary,
+    AccountCommand, AttachmentUpload, Command, CommandOutput, ConnectionState, CreateRoomOptions,
+    EncryptionCommand, EncryptionState, Error, ErrorKind, Event, InteractiveAuth,
+    InteractiveAuthOutcome, LifecycleCommand, Media, MediaCommand, MediaId, MediaSize,
+    MemberFilter, MemberSummary, MessageContent, MessageEditContent, NotificationCommand,
+    OwnDevice, PowerLevelChanges, Profile, PushNotification, PushNotificationEvent,
+    PushNotificationStatus, RoomCommand, RoomListFilter, RoomNotificationMode,
+    RoomNotificationSettings, RoomPowerLevels, RoomSummary, SpaceChild, TimelineCommand,
+    TimelineId, VerificationAction, VerificationTarget,
     encryption::encryption_state,
+    engine::MediaService,
     model::{PushNotificationRoom, PushNotificationSender},
-    normalise::{member_summary, room_summaries},
+    normalise::{member_summary, room_summaries, space_child},
 };
 
 #[derive(Clone)]
 pub struct ClientHandle {
-    commands: mpsc::Sender<DriverRequest>,
-    next_id: Arc<AtomicU64>,
+    requests: mpsc::Sender<Request>,
     client: Client,
     connection: watch::Receiver<ConnectionState>,
     notification_client: Arc<OnceCell<NotificationClient>>,
     sync_service: Arc<SyncService>,
+    media: Arc<MediaService>,
+    spaces: Arc<OnceCell<SpaceService>>,
 }
 
 impl fmt::Debug for ClientHandle {
@@ -54,73 +59,154 @@ impl fmt::Debug for ClientHandle {
     }
 }
 
+/// a command's answer. drop it if you don't care, the command still runs
+#[derive(Debug)]
+#[must_use = "dropping it is fine but then you'll never know"]
+pub struct Pending(oneshot::Receiver<Result<CommandOutput, Error>>);
+
+impl Future for Pending {
+    type Output = Result<CommandOutput, Error>;
+
+    fn poll(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
+        Pin::new(&mut self.0)
+            .poll(context)
+            .map(|result| result.unwrap_or_else(|_| Err(Error::interrupted())))
+    }
+}
+
 impl ClientHandle {
-    /// Current credentials after a refresh. Persist this snapshot atomically
-    /// when `Event::SessionTokensChanged` arrives; it contains secrets.
+    /// current credentials. persist this atomically on `Event::SessionTokensChanged`, it holds secrets
     #[cfg(feature = "sqlite")]
     pub fn session_record(&self) -> Result<crate::SessionRecord, crate::AccountError> {
         crate::account::session_record(&self.client)
     }
 
-    /// Queue a command and return its correlation ID, not its result. Drain
-    /// `EventStream` concurrently and match one terminal result event by ID.
-    /// A successful timeline send only means the SDK queue accepted it.
-    pub async fn send(&self, command: Command) -> Result<CommandId, SendCommandError> {
-        let id = self.next_command_id();
-        self.commands
-            .send(DriverRequest::Command(CommandEnvelope { id, command }))
+    /// queue a command, waiting for room in the queue if there isn't any
+    pub async fn send(&self, command: Command) -> Result<Pending, Error> {
+        let (request, pending) = Request::new(command);
+        self.requests
+            .send(request)
             .await
-            .map_err(|_| SendCommandError::Closed)?;
-        Ok(id)
+            .map_err(|_| Error::interrupted())?;
+        Ok(pending)
+    }
+
+    /// queue a command or fail with `QueueFull` right now
+    pub fn try_send(&self, command: Command) -> Result<Pending, Error> {
+        let (request, pending) = Request::new(command);
+        self.requests
+            .try_send(request)
+            .map_err(|error| match error {
+                mpsc::error::TrySendError::Full(_) => {
+                    Error::new(ErrorKind::QueueFull, "the command queue is full")
+                }
+                mpsc::error::TrySendError::Closed(_) => Error::interrupted(),
+            })?;
+        Ok(pending)
+    }
+
+    /// queue a command and wait for its answer. timeline sends answer once the
+    /// sdk send queue has them, delivery shows up later as the item's send state
+    pub async fn execute(&self, command: Command) -> Result<CommandOutput, Error> {
+        self.send(command).await?.await
+    }
+
+    async fn run(&self, command: Command) -> Result<(), Error> {
+        self.execute(command).await.map(drop)
+    }
+
+    async fn run_for_room(&self, command: RoomCommand) -> Result<OwnedRoomId, Error> {
+        match self.execute(Command::Room(command)).await? {
+            CommandOutput::Room(room_id) => Ok(room_id),
+            output => Err(Error::new(
+                ErrorKind::Other,
+                format!("expected a room but got {output:?}"),
+            )),
+        }
+    }
+
+    pub async fn shutdown(&self) -> Result<(), Error> {
+        self.run(Command::Lifecycle(LifecycleCommand::Shutdown))
+            .await
+    }
+
+    pub async fn logout(&self) -> Result<(), Error> {
+        self.run(Command::Account(AccountCommand::Logout)).await
     }
 
     pub async fn delete_devices(
         &self,
-        device_ids: Vec<ruma::OwnedDeviceId>,
+        device_ids: Vec<OwnedDeviceId>,
         auth: Option<InteractiveAuth>,
-    ) -> Result<InteractiveAuthOutcome, CommandResultError> {
-        let (reply, result) = oneshot::channel();
-        self.commands
-            .send(DriverRequest::DeleteDevices {
-                id: self.next_command_id(),
+    ) -> Result<InteractiveAuthOutcome, Error> {
+        match self
+            .run(Command::Account(AccountCommand::DeleteDevices {
                 device_ids,
                 auth,
-                reply,
-            })
+            }))
             .await
-            .map_err(|_| SendCommandError::Closed)?;
-        result.await.map_err(|_| CommandResultError::Closed)?
+        {
+            Ok(()) => Ok(InteractiveAuthOutcome::Completed),
+            Err(Error {
+                challenge: Some(challenge),
+                ..
+            }) => Ok(InteractiveAuthOutcome::Challenge(*challenge)),
+            Err(error) => Err(error),
+        }
     }
 
     pub async fn rename_device(
         &self,
-        device_id: ruma::OwnedDeviceId,
+        device_id: OwnedDeviceId,
         display_name: impl Into<String>,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Account(AccountCommand::RenameDevice {
+    ) -> Result<(), Error> {
+        self.run(Command::Account(AccountCommand::RenameDevice {
             device_id,
             display_name: display_name.into(),
         }))
         .await
     }
 
+    pub async fn set_global_account_data(
+        &self,
+        event_type: GlobalAccountDataEventType,
+        content: Raw<AnyGlobalAccountDataEventContent>,
+    ) -> Result<(), Error> {
+        self.run(Command::Account(AccountCommand::SetAccountData {
+            event_type,
+            content,
+        }))
+        .await
+    }
+
+    pub async fn set_room_account_data(
+        &self,
+        room_id: OwnedRoomId,
+        event_type: RoomAccountDataEventType,
+        content: Raw<AnyRoomAccountDataEventContent>,
+    ) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::SetAccountData {
+            room_id,
+            event_type,
+            content,
+        }))
+        .await
+    }
+
     pub async fn set_room_notification_mode(
         &self,
-        room_id: ruma::OwnedRoomId,
+        room_id: OwnedRoomId,
         mode: RoomNotificationMode,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Notification(NotificationCommand::SetRoomMode {
+    ) -> Result<(), Error> {
+        self.run(Command::Notification(NotificationCommand::SetRoomMode {
             room_id,
             mode,
         }))
         .await
     }
 
-    pub async fn reset_room_notification_mode(
-        &self,
-        room_id: ruma::OwnedRoomId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Notification(NotificationCommand::ResetRoomMode(
+    pub async fn reset_room_notification_mode(&self, room_id: OwnedRoomId) -> Result<(), Error> {
+        self.run(Command::Notification(NotificationCommand::ResetRoomMode(
             room_id,
         )))
         .await
@@ -131,8 +217,8 @@ impl ClientHandle {
         encrypted: bool,
         one_to_one: bool,
         mode: RoomNotificationMode,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Notification(NotificationCommand::SetDefaultMode {
+    ) -> Result<(), Error> {
+        self.run(Command::Notification(NotificationCommand::SetDefaultMode {
             encrypted,
             one_to_one,
             mode,
@@ -140,11 +226,8 @@ impl ClientHandle {
         .await
     }
 
-    pub async fn add_notification_keyword(
-        &self,
-        keyword: impl Into<String>,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Notification(NotificationCommand::AddKeyword(
+    pub async fn add_notification_keyword(&self, keyword: impl Into<String>) -> Result<(), Error> {
+        self.run(Command::Notification(NotificationCommand::AddKeyword(
             keyword.into(),
         )))
         .await
@@ -153,35 +236,27 @@ impl ClientHandle {
     pub async fn remove_notification_keyword(
         &self,
         keyword: impl Into<String>,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Notification(NotificationCommand::RemoveKeyword(
+    ) -> Result<(), Error> {
+        self.run(Command::Notification(NotificationCommand::RemoveKeyword(
             keyword.into(),
         )))
         .await
     }
 
-    pub async fn open_room(
-        &self,
-        room_id: ruma::OwnedRoomId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::Open(room_id)))
-            .await
+    pub async fn open_room(&self, room_id: OwnedRoomId) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::Open(room_id))).await
     }
 
-    pub async fn close_room(
-        &self,
-        room_id: ruma::OwnedRoomId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::Close(room_id)))
-            .await
+    pub async fn close_room(&self, room_id: OwnedRoomId) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::Close(room_id))).await
     }
 
     pub async fn open_thread(
         &self,
-        room_id: ruma::OwnedRoomId,
-        root_event_id: ruma::OwnedEventId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Timeline(crate::TimelineCommand::OpenThread {
+        room_id: OwnedRoomId,
+        root_event_id: OwnedEventId,
+    ) -> Result<(), Error> {
+        self.run(Command::Timeline(TimelineCommand::OpenThread {
             room_id,
             root_event_id,
         }))
@@ -190,76 +265,142 @@ impl ClientHandle {
 
     pub async fn close_thread(
         &self,
-        room_id: ruma::OwnedRoomId,
-        root_event_id: ruma::OwnedEventId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Timeline(crate::TimelineCommand::CloseThread {
+        room_id: OwnedRoomId,
+        root_event_id: OwnedEventId,
+    ) -> Result<(), Error> {
+        self.run(Command::Timeline(TimelineCommand::CloseThread {
             room_id,
             root_event_id,
         }))
         .await
     }
 
-    pub async fn join_room(
-        &self,
-        room: ruma::OwnedRoomOrAliasId,
-        via: Vec<ruma::OwnedServerName>,
-    ) -> Result<ruma::OwnedRoomId, CommandResultError> {
-        self.room_result(crate::RoomCommand::Join { room, via })
+    pub async fn resync(&self, timeline_id: TimelineId) -> Result<(), Error> {
+        self.run(Command::Timeline(TimelineCommand::Resync { timeline_id }))
             .await
     }
 
-    pub async fn leave_room(
+    pub async fn paginate(&self, timeline_id: TimelineId, limit: u16) -> Result<(), Error> {
+        self.run(Command::Timeline(TimelineCommand::Paginate {
+            timeline_id,
+            limit,
+        }))
+        .await
+    }
+
+    pub async fn send_message(
         &self,
-        room_id: ruma::OwnedRoomId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::Leave(room_id)))
-            .await
+        timeline_id: TimelineId,
+        content: MessageContent,
+    ) -> Result<(), Error> {
+        self.run(Command::Timeline(TimelineCommand::Send {
+            timeline_id,
+            content,
+        }))
+        .await
     }
 
-    pub async fn forget_room(
+    pub async fn edit_message(
         &self,
-        room_id: ruma::OwnedRoomId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::Forget(room_id)))
-            .await
+        timeline_id: TimelineId,
+        event_id: OwnedEventId,
+        content: MessageEditContent,
+    ) -> Result<(), Error> {
+        self.run(Command::Timeline(TimelineCommand::Edit {
+            timeline_id,
+            event_id,
+            content,
+        }))
+        .await
     }
 
-    pub async fn accept_invite(
+    pub async fn redact(
         &self,
-        room_id: ruma::OwnedRoomId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::AcceptInvite(room_id)))
+        timeline_id: TimelineId,
+        event_id: OwnedEventId,
+        reason: Option<String>,
+    ) -> Result<(), Error> {
+        self.run(Command::Timeline(TimelineCommand::Redact {
+            timeline_id,
+            event_id,
+            reason,
+        }))
+        .await
+    }
+
+    pub async fn toggle_reaction(
+        &self,
+        timeline_id: TimelineId,
+        event_id: OwnedEventId,
+        key: impl Into<String>,
+    ) -> Result<(), Error> {
+        self.run(Command::Timeline(TimelineCommand::ToggleReaction {
+            timeline_id,
+            event_id,
+            key: key.into(),
+        }))
+        .await
+    }
+
+    pub async fn mark_read(
+        &self,
+        timeline_id: TimelineId,
+        event_id: OwnedEventId,
+    ) -> Result<(), Error> {
+        self.run(Command::Timeline(TimelineCommand::MarkRead {
+            timeline_id,
+            event_id,
+        }))
+        .await
+    }
+
+    pub async fn set_typing(&self, room_id: OwnedRoomId, typing: bool) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::SetTyping { room_id, typing }))
             .await
     }
 
-    pub async fn reject_invite(
+    pub async fn join_room(
         &self,
-        room_id: ruma::OwnedRoomId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::RejectInvite(room_id)))
+        room: OwnedRoomOrAliasId,
+        via: Vec<OwnedServerName>,
+    ) -> Result<OwnedRoomId, Error> {
+        self.run_for_room(RoomCommand::Join { room, via }).await
+    }
+
+    pub async fn leave_room(&self, room_id: OwnedRoomId) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::Leave(room_id))).await
+    }
+
+    pub async fn forget_room(&self, room_id: OwnedRoomId) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::Forget(room_id))).await
+    }
+
+    pub async fn accept_invite(&self, room_id: OwnedRoomId) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::AcceptInvite(room_id)))
+            .await
+    }
+
+    pub async fn reject_invite(&self, room_id: OwnedRoomId) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::RejectInvite(room_id)))
             .await
     }
 
     pub async fn invite_user(
         &self,
-        room_id: ruma::OwnedRoomId,
-        user_id: ruma::OwnedUserId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::InviteUser {
-            room_id,
-            user_id,
-        }))
-        .await
+        room_id: OwnedRoomId,
+        user_id: OwnedUserId,
+    ) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::InviteUser { room_id, user_id }))
+            .await
     }
 
     pub async fn kick_user(
         &self,
-        room_id: ruma::OwnedRoomId,
-        user_id: ruma::OwnedUserId,
+        room_id: OwnedRoomId,
+        user_id: OwnedUserId,
         reason: Option<String>,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::KickUser {
+    ) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::KickUser {
             room_id,
             user_id,
             reason,
@@ -269,11 +410,11 @@ impl ClientHandle {
 
     pub async fn ban_user(
         &self,
-        room_id: ruma::OwnedRoomId,
-        user_id: ruma::OwnedUserId,
+        room_id: OwnedRoomId,
+        user_id: OwnedUserId,
         reason: Option<String>,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::BanUser {
+    ) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::BanUser {
             room_id,
             user_id,
             reason,
@@ -283,11 +424,11 @@ impl ClientHandle {
 
     pub async fn unban_user(
         &self,
-        room_id: ruma::OwnedRoomId,
-        user_id: ruma::OwnedUserId,
+        room_id: OwnedRoomId,
+        user_id: OwnedUserId,
         reason: Option<String>,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::UnbanUser {
+    ) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::UnbanUser {
             room_id,
             user_id,
             reason,
@@ -297,10 +438,10 @@ impl ClientHandle {
 
     pub async fn set_power_levels(
         &self,
-        room_id: ruma::OwnedRoomId,
+        room_id: OwnedRoomId,
         changes: PowerLevelChanges,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::SetPowerLevels {
+    ) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::SetPowerLevels {
             room_id,
             changes,
         }))
@@ -309,11 +450,11 @@ impl ClientHandle {
 
     pub async fn set_user_power_level(
         &self,
-        room_id: ruma::OwnedRoomId,
-        user_id: ruma::OwnedUserId,
+        room_id: OwnedRoomId,
+        user_id: OwnedUserId,
         level: i64,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::SetUserPowerLevel {
+    ) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::SetUserPowerLevel {
             room_id,
             user_id,
             level,
@@ -321,43 +462,21 @@ impl ClientHandle {
         .await
     }
 
-    pub async fn create_room(
-        &self,
-        options: crate::CreateRoomOptions,
-    ) -> Result<ruma::OwnedRoomId, CommandResultError> {
-        self.room_result(crate::RoomCommand::Create(options)).await
-    }
-
-    pub async fn create_direct(
-        &self,
-        user_id: ruma::OwnedUserId,
-    ) -> Result<ruma::OwnedRoomId, CommandResultError> {
-        self.room_result(crate::RoomCommand::CreateDirect(user_id))
-            .await
+    pub async fn create_room(&self, options: CreateRoomOptions) -> Result<OwnedRoomId, Error> {
+        self.run_for_room(RoomCommand::Create(options)).await
     }
 
-    async fn room_result(
-        &self,
-        command: crate::RoomCommand,
-    ) -> Result<ruma::OwnedRoomId, CommandResultError> {
-        let (reply, result) = oneshot::channel();
-        self.commands
-            .send(DriverRequest::RoomResult {
-                id: self.next_command_id(),
-                command,
-                reply,
-            })
-            .await
-            .map_err(|_| SendCommandError::Closed)?;
-        result.await.map_err(|_| CommandResultError::Closed)?
+    /// hands back the existing dm with them if there is one
+    pub async fn create_direct(&self, user_id: OwnedUserId) -> Result<OwnedRoomId, Error> {
+        self.run_for_room(RoomCommand::CreateDirect(user_id)).await
     }
 
     pub async fn cancel_send(
         &self,
-        room_id: ruma::OwnedRoomId,
-        transaction_id: ruma::OwnedTransactionId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::CancelSend {
+        room_id: OwnedRoomId,
+        transaction_id: OwnedTransactionId,
+    ) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::CancelSend {
             room_id,
             transaction_id,
         }))
@@ -366,134 +485,152 @@ impl ClientHandle {
 
     pub async fn retry_send(
         &self,
-        room_id: ruma::OwnedRoomId,
-        transaction_id: ruma::OwnedTransactionId,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Room(crate::RoomCommand::RetrySend {
+        room_id: OwnedRoomId,
+        transaction_id: OwnedTransactionId,
+    ) -> Result<(), Error> {
+        self.run(Command::Room(RoomCommand::RetrySend {
             room_id,
             transaction_id,
         }))
         .await
     }
 
-    pub async fn upload_media(
-        &self,
-        timeline_id: crate::TimelineId,
-        filename: String,
-        mimetype: String,
-        bytes: Vec<u8>,
-        caption: Option<String>,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Media(crate::MediaCommand::Upload {
-            timeline_id,
-            filename,
-            mimetype,
-            bytes,
-            caption,
-        }))
-        .await
+    pub async fn upload(&self, upload: AttachmentUpload) -> Result<(), Error> {
+        self.run(Command::Media(MediaCommand::Upload(upload))).await
     }
 
-    pub async fn upload_attachment(
-        &self,
-        upload: crate::AttachmentUpload,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Media(crate::MediaCommand::UploadAttachment(
-            upload,
+    pub async fn recover(&self, recovery_key: impl Into<String>) -> Result<(), Error> {
+        self.run(Command::Encryption(EncryptionCommand::Recover(
+            recovery_key.into(),
         )))
         .await
     }
 
-    pub async fn create_key_backup(&self) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Encryption(
-            crate::EncryptionCommand::CreateKeyBackup,
-        ))
-        .await
+    pub async fn create_key_backup(&self) -> Result<(), Error> {
+        self.run(Command::Encryption(EncryptionCommand::CreateKeyBackup))
+            .await
     }
 
-    pub async fn enable_key_backup(&self) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Encryption(
-            crate::EncryptionCommand::EnableKeyBackup,
-        ))
-        .await
+    pub async fn enable_key_backup(&self) -> Result<(), Error> {
+        self.run(Command::Encryption(EncryptionCommand::EnableKeyBackup))
+            .await
     }
 
-    pub async fn disable_key_backup(
-        &self,
-        delete_from_server: bool,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Encryption(
-            crate::EncryptionCommand::DisableKeyBackup { delete_from_server },
-        ))
+    pub async fn disable_key_backup(&self, delete_from_server: bool) -> Result<(), Error> {
+        self.run(Command::Encryption(EncryptionCommand::DisableKeyBackup {
+            delete_from_server,
+        }))
         .await
     }
 
-    pub async fn recover_key_backup(
-        &self,
-        recovery_key: impl Into<String>,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Encryption(
-            crate::EncryptionCommand::RecoverKeyBackup(recovery_key.into()),
-        ))
+    pub async fn recover_key_backup(&self, recovery_key: impl Into<String>) -> Result<(), Error> {
+        self.run(Command::Encryption(EncryptionCommand::RecoverKeyBackup(
+            recovery_key.into(),
+        )))
         .await
     }
 
-    pub async fn start_verification(
-        &self,
-        target: crate::VerificationTarget,
-    ) -> Result<CommandId, SendCommandError> {
-        self.send(Command::Encryption(
-            crate::EncryptionCommand::StartVerification(target),
-        ))
+    pub async fn start_verification(&self, target: VerificationTarget) -> Result<(), Error> {
+        self.run(Command::Encryption(EncryptionCommand::StartVerification(
+            target,
+        )))
         .await
     }
 
-    pub fn try_send(&self, command: Command) -> Result<CommandId, SendCommandError> {
-        let id = self.next_command_id();
-        self.commands
-            .try_send(DriverRequest::Command(CommandEnvelope { id, command }))
-            .map_err(|error| match error {
-                mpsc::error::TrySendError::Full(_) => SendCommandError::Full,
-                mpsc::error::TrySendError::Closed(_) => SendCommandError::Closed,
-            })?;
-        Ok(id)
+    pub async fn verify(&self, action: VerificationAction) -> Result<(), Error> {
+        self.run(Command::Encryption(EncryptionCommand::Verify(action)))
+            .await
     }
 
-    fn next_command_id(&self) -> CommandId {
-        CommandId::new(self.next_id.fetch_add(1, Ordering::Relaxed))
+    /// bytes for media a retained timeline showed you. concurrent asks share one download
+    pub async fn media(&self, media_id: &MediaId, size: MediaSize) -> Result<Media, Error> {
+        self.media.timeline_media(media_id, size).await
+    }
+
+    /// bytes for any plain mxc uri, avatars mostly. same byte cap as everything else
+    pub async fn mxc_media(&self, uri: &MxcUri, size: MediaSize) -> Result<Media, Error> {
+        self.media.mxc_media(uri, size).await
+    }
+
+    /// the space graph builds on first use and then keeps itself current
+    async fn spaces(&self) -> &SpaceService {
+        self.spaces
+            .get_or_init(|| SpaceService::new(self.client.clone()))
+            .await
     }
 
     pub async fn rooms(&self) -> Vec<RoomSummary> {
-        room_summaries(&self.client).await
+        room_summaries(&self.client, self.spaces().await).await
     }
 
-    pub async fn rooms_filtered(&self, filter: &RoomListFilter) -> Vec<RoomSummary> {
-        let mut room_filter = filter.clone();
-        let search = room_filter
-            .search
-            .take()
-            .map(|search| search.to_lowercase());
+    /// browse a space the way the server sees it, rooms you haven't joined included
+    pub async fn space_hierarchy(&self, space_id: OwnedRoomId) -> SpaceHierarchy {
+        SpaceHierarchy(SpaceRoomList::new(self.client.clone(), space_id).await)
+    }
+
+    pub async fn own_profile(&self) -> Result<Profile, Error> {
+        let user_id = self
+            .client
+            .user_id()
+            .ok_or_else(|| Error::new(ErrorKind::Unauthenticated, "the client is not logged in"))?
+            .to_owned();
+        let response = self
+            .client
+            .account()
+            .fetch_user_profile()
+            .await
+            .map_err(|source| Error::from_sdk("fetching the profile failed", source))?;
+        profile(user_id, &response)
+    }
+
+    pub async fn user_profile(&self, user_id: &UserId) -> Result<Profile, Error> {
+        let response = self
+            .client
+            .account()
+            .fetch_user_profile_of(user_id)
+            .await
+            .map_err(|source| Error::from_sdk("fetching the profile failed", source))?;
+        profile(user_id.to_owned(), &response)
+    }
+
+    pub async fn set_display_name(&self, name: Option<String>) -> Result<(), Error> {
+        self.run(Command::Account(AccountCommand::SetDisplayName(name)))
+            .await
+    }
+
+    pub async fn set_avatar(&self, avatar: Option<OwnedMxcUri>) -> Result<(), Error> {
+        self.run(Command::Account(AccountCommand::SetAvatar(avatar)))
+            .await
+    }
+
+    pub async fn upload_avatar(
+        &self,
+        mimetype: impl Into<String>,
+        bytes: Vec<u8>,
+    ) -> Result<(), Error> {
+        self.run(Command::Account(AccountCommand::UploadAvatar {
+            mimetype: mimetype.into(),
+            bytes,
+        }))
+        .await
+    }
 
+    pub async fn rooms_filtered(&self, filter: &RoomListFilter) -> Vec<RoomSummary> {
+        let matcher = filter.matcher();
         self.rooms()
             .await
             .into_iter()
-            .filter(|room| {
-                room_filter.matches(room)
-                    && search.as_ref().is_none_or(|search| {
-                        room.name.to_lowercase().contains(search)
-                            || room.room_id.as_str().to_lowercase().contains(search)
-                    })
-            })
+            .filter(|room| matcher.matches(room))
             .collect()
     }
 
-    pub async fn devices(&self) -> Result<Vec<OwnDevice>, ClientQueryError> {
+    pub async fn devices(&self) -> Result<Vec<OwnDevice>, Error> {
         let current_device_id = self.client.device_id();
         Ok(self
             .client
             .devices()
             .await
-            .map_err(|source| ClientQueryError::Sdk(source.into()))?
+            .map_err(|source| Error::from_http("listing devices failed", source))?
             .devices
             .into_iter()
             .map(|device| OwnDevice {
@@ -506,14 +643,17 @@ impl ClientHandle {
             .collect())
     }
 
+    fn room(&self, room_id: &RoomId) -> Result<matrix_sdk::Room, Error> {
+        self.client
+            .get_room(room_id)
+            .ok_or_else(Error::room_unknown)
+    }
+
     pub async fn room_notification_settings(
         &self,
         room_id: &RoomId,
-    ) -> Result<Option<RoomNotificationSettings>, ClientQueryError> {
-        let room = self
-            .client
-            .get_room(room_id)
-            .ok_or_else(|| ClientQueryError::RoomUnknown(room_id.to_owned()))?;
+    ) -> Result<Option<RoomNotificationSettings>, Error> {
+        let room = self.room(room_id)?;
         let custom = room.user_defined_notification_mode().await;
         let mode = match custom {
             Some(mode) => mode,
@@ -542,7 +682,14 @@ impl ClientHandle {
         &self,
         room_id: &RoomId,
         event_id: &EventId,
-    ) -> Result<PushNotificationStatus, ClientQueryError> {
+    ) -> Result<PushNotificationStatus, Error> {
+        let notification_failed = |source| {
+            Error::with_source(
+                ErrorKind::Other,
+                "resolving the push notification failed",
+                source,
+            )
+        };
         let client = self
             .notification_client
             .get_or_try_init(|| async {
@@ -555,11 +702,11 @@ impl ClientHandle {
                 .await
             })
             .await
-            .map_err(ClientQueryError::Notification)?;
+            .map_err(notification_failed)?;
         let status = client
             .get_notification(room_id, event_id)
             .await
-            .map_err(ClientQueryError::Notification)?;
+            .map_err(notification_failed)?;
         Ok(normalise_push_notification(room_id, event_id, status))
     }
 
@@ -567,11 +714,7 @@ impl ClientHandle {
         &self,
         room_id: &RoomId,
         filter: MemberFilter,
-    ) -> Result<Vec<MemberSummary>, ClientQueryError> {
-        let room = self
-            .client
-            .get_room(room_id)
-            .ok_or_else(|| ClientQueryError::RoomUnknown(room_id.to_owned()))?;
+    ) -> Result<Vec<MemberSummary>, Error> {
         let memberships = match filter {
             MemberFilter::Active => RoomMemberships::ACTIVE,
             MemberFilter::Joined => RoomMemberships::JOIN,
@@ -580,27 +723,22 @@ impl ClientHandle {
             // membership, including custom states that `all()` would exclude.
             MemberFilter::All => RoomMemberships::empty(),
         };
-        Ok(room
+        Ok(self
+            .room(room_id)?
             .members(memberships)
             .await
-            .map_err(ClientQueryError::Sdk)?
+            .map_err(|source| Error::from_sdk("listing members failed", source))?
             .into_iter()
             .map(member_summary)
             .collect())
     }
 
-    pub async fn room_power_levels(
-        &self,
-        room_id: &RoomId,
-    ) -> Result<RoomPowerLevels, ClientQueryError> {
-        let room = self
-            .client
-            .get_room(room_id)
-            .ok_or_else(|| ClientQueryError::RoomUnknown(room_id.to_owned()))?;
-        let levels = room
+    pub async fn room_power_levels(&self, room_id: &RoomId) -> Result<RoomPowerLevels, Error> {
+        let levels = self
+            .room(room_id)?
             .power_levels()
             .await
-            .map_err(|source| ClientQueryError::Sdk(source.into()))?;
+            .map_err(|source| Error::from_sdk("reading power levels failed", source.into()))?;
         Ok(RoomPowerLevels {
             ban: levels.ban.into(),
             invite: levels.invite.into(),
@@ -626,16 +764,15 @@ impl ClientHandle {
     pub async fn pending_send_ids(
         &self,
         room_id: &RoomId,
-    ) -> Result<Vec<ruma::OwnedTransactionId>, ClientQueryError> {
-        let room = self
-            .client
-            .get_room(room_id)
-            .ok_or_else(|| ClientQueryError::RoomUnknown(room_id.to_owned()))?;
-        let (echoes, _) = room
+    ) -> Result<Vec<OwnedTransactionId>, Error> {
+        let (echoes, _) = self
+            .room(room_id)?
             .send_queue()
             .subscribe()
             .await
-            .map_err(ClientQueryError::SendQueue)?;
+            .map_err(|source| {
+                Error::with_source(ErrorKind::Store, "reading the send queue failed", source)
+            })?;
         Ok(echoes
             .into_iter()
             .filter(|echo| {
@@ -651,62 +788,23 @@ impl ClientHandle {
     pub async fn global_account_data(
         &self,
         event_type: GlobalAccountDataEventType,
-    ) -> Result<Option<Raw<AnyGlobalAccountDataEventContent>>, ClientQueryError> {
+    ) -> Result<Option<Raw<AnyGlobalAccountDataEventContent>>, Error> {
         self.client
             .account()
             .account_data_raw(event_type)
             .await
-            .map_err(ClientQueryError::Sdk)
-    }
-
-    pub async fn set_global_account_data(
-        &self,
-        event_type: GlobalAccountDataEventType,
-        content: Raw<AnyGlobalAccountDataEventContent>,
-    ) -> Result<(), ClientQueryError> {
-        let (reply, result) = oneshot::channel();
-        self.commands
-            .send(DriverRequest::SetGlobalAccountData {
-                event_type,
-                content,
-                reply,
-            })
-            .await
-            .map_err(|_| ClientQueryError::EngineStopped)?;
-        result.await.map_err(|_| ClientQueryError::EngineStopped)?
+            .map_err(|source| Error::from_sdk("reading account data failed", source))
     }
 
     pub async fn room_account_data(
         &self,
         room_id: &RoomId,
         event_type: RoomAccountDataEventType,
-    ) -> Result<Option<Raw<AnyRoomAccountDataEvent>>, ClientQueryError> {
-        let room = self
-            .client
-            .get_room(room_id)
-            .ok_or_else(|| ClientQueryError::RoomUnknown(room_id.to_owned()))?;
-        room.account_data(event_type)
-            .await
-            .map_err(ClientQueryError::Sdk)
-    }
-
-    pub async fn set_room_account_data(
-        &self,
-        room_id: &RoomId,
-        event_type: RoomAccountDataEventType,
-        content: Raw<ruma::events::AnyRoomAccountDataEventContent>,
-    ) -> Result<(), ClientQueryError> {
-        let (reply, result) = oneshot::channel();
-        self.commands
-            .send(DriverRequest::SetRoomAccountData {
-                room_id: room_id.to_owned(),
-                event_type,
-                content,
-                reply,
-            })
+    ) -> Result<Option<Raw<AnyRoomAccountDataEvent>>, Error> {
+        self.room(room_id)?
+            .account_data(event_type)
             .await
-            .map_err(|_| ClientQueryError::EngineStopped)?;
-        result.await.map_err(|_| ClientQueryError::EngineStopped)?
+            .map_err(|source| Error::from_sdk("reading room account data failed", source))
     }
 
     #[must_use]
@@ -727,37 +825,96 @@ impl ClientHandle {
     }
 }
 
-#[derive(Debug, Eq, PartialEq)]
-pub(crate) struct CommandEnvelope {
-    pub(crate) id: CommandId,
+/// one space's hierarchy, a page at a time. hold on to it while you browse, it remembers where it got to
+pub struct SpaceHierarchy(SpaceRoomList);
+
+impl fmt::Debug for SpaceHierarchy {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("SpaceHierarchy")
+            .finish_non_exhaustive()
+    }
+}
+
+impl SpaceHierarchy {
+    /// fetches the next page. a no-op once the end is reached or while a page is in flight
+    pub async fn paginate(&self) -> Result<(), Error> {
+        self.0.paginate().await.map_err(|source| {
+            Error::with_source(
+                ErrorKind::Server,
+                "fetching the space hierarchy failed",
+                source,
+            )
+        })
+    }
+
+    /// everything fetched so far, the space itself excluded
+    pub async fn rooms(&self) -> Vec<SpaceChild> {
+        self.0.rooms().await.into_iter().map(space_child).collect()
+    }
+
+    #[must_use]
+    pub fn end_reached(&self) -> bool {
+        matches!(
+            self.0.pagination_state(),
+            SpaceRoomListPaginationState::Idle { end_reached: true }
+        )
+    }
+}
+
+fn profile(
+    user_id: OwnedUserId,
+    response: &ruma::api::client::profile::get_profile::v3::Response,
+) -> Result<Profile, Error> {
+    use ruma::api::client::profile::{AvatarUrl, DisplayName};
+    let malformed = |source| {
+        Error::with_source(
+            ErrorKind::Server,
+            "the server sent a malformed profile",
+            source,
+        )
+    };
+    Ok(Profile {
+        user_id,
+        display_name: response.get_static::<DisplayName>().map_err(malformed)?,
+        avatar: response.get_static::<AvatarUrl>().map_err(malformed)?,
+    })
+}
+
+#[derive(Debug)]
+pub(crate) struct Request {
     pub(crate) command: Command,
+    pub(crate) reply: Responder,
+}
+
+impl Request {
+    fn new(command: Command) -> (Self, Pending) {
+        let (reply, pending) = oneshot::channel();
+        (
+            Self {
+                command,
+                reply: Responder(reply),
+            },
+            Pending(pending),
+        )
+    }
 }
 
+/// whoever holds this owes the caller an answer. dropping it answers `Interrupted`
 #[derive(Debug)]
-pub(crate) enum DriverRequest {
-    Command(CommandEnvelope),
-    DeleteDevices {
-        id: CommandId,
-        device_ids: Vec<ruma::OwnedDeviceId>,
-        auth: Option<InteractiveAuth>,
-        reply: oneshot::Sender<Result<InteractiveAuthOutcome, CommandResultError>>,
-    },
-    RoomResult {
-        id: CommandId,
-        command: crate::RoomCommand,
-        reply: oneshot::Sender<Result<ruma::OwnedRoomId, CommandResultError>>,
-    },
-    SetGlobalAccountData {
-        event_type: GlobalAccountDataEventType,
-        content: Raw<AnyGlobalAccountDataEventContent>,
-        reply: oneshot::Sender<Result<(), ClientQueryError>>,
-    },
-    SetRoomAccountData {
-        room_id: ruma::OwnedRoomId,
-        event_type: RoomAccountDataEventType,
-        content: Raw<ruma::events::AnyRoomAccountDataEventContent>,
-        reply: oneshot::Sender<Result<(), ClientQueryError>>,
-    },
+pub(crate) struct Responder(oneshot::Sender<Result<CommandOutput, Error>>);
+
+impl Responder {
+    pub(crate) fn send(self, result: Result<CommandOutput, Error>) {
+        if let Err(error) = &result {
+            tracing::debug!(%error, kind = ?error.kind, "command failed");
+        }
+        let _ = self.0.send(result);
+    }
+
+    pub(crate) fn done(self, result: Result<(), Error>) {
+        self.send(result.map(|()| CommandOutput::Done));
+    }
 }
 
 #[derive(Debug)]
@@ -785,7 +942,7 @@ impl futures_util::Stream for EventStream {
 
 #[derive(Debug)]
 pub(crate) struct DriverPort {
-    commands: mpsc::Receiver<DriverRequest>,
+    requests: mpsc::Receiver<Request>,
     events: mpsc::Sender<Event>,
     connection: watch::Sender<ConnectionState>,
 }
@@ -795,11 +952,10 @@ pub(crate) struct EventSender(mpsc::Sender<Event>);
 
 impl EventSender {
     pub(crate) async fn send(&self, event: Event) -> Result<(), SendEventError> {
-        self.0.send(event).await.map_err(|_| SendEventError::Closed)
+        self.0.send(event).await.map_err(|_| SendEventError)
     }
 
-    /// Resolves once every [`EventStream`] receiver has been dropped, so the
-    /// engine can notice a lost event consumer inside a `select!`.
+    /// resolves once every `EventStream` is gone
     pub(crate) async fn closed(&self) {
         self.0.closed().await;
     }
@@ -814,74 +970,42 @@ impl DriverPort {
         self.connection.clone()
     }
 
-    pub async fn recv(&mut self) -> Option<DriverRequest> {
-        self.commands.recv().await
+    pub(crate) async fn recv(&mut self) -> Option<Request> {
+        self.requests.recv().await
     }
 
-    pub async fn send(&self, event: Event) -> Result<(), SendEventError> {
-        self.event_sender().send(event).await
+    pub(crate) fn close(&mut self) {
+        self.requests.close();
     }
 }
 
-#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
-pub enum SendCommandError {
-    #[error("the command channel is full")]
-    Full,
-    #[error("the engine has stopped")]
-    Closed,
-}
-
-#[derive(Debug, Error)]
-pub enum CommandResultError {
-    #[error(transparent)]
-    Send(#[from] SendCommandError),
-    #[error("the engine stopped before the operation completed")]
-    Closed,
-    #[error("{}", .0.message)]
-    Failed(crate::CommandFailure),
-}
-
-#[derive(Debug, Error)]
-pub enum ClientQueryError {
-    #[error("room {0} is not available in the local store")]
-    RoomUnknown(ruma::OwnedRoomId),
-    #[error("Matrix query failed")]
-    Sdk(#[source] matrix_sdk::Error),
-    #[error("reading the send queue failed")]
-    SendQueue(#[source] matrix_sdk::send_queue::RoomSendQueueError),
-    #[error("resolving the push notification failed")]
-    Notification(#[source] matrix_sdk_ui::notification_client::Error),
-    #[error("the engine stopped before the operation completed")]
-    EngineStopped,
-}
-
-#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
-pub(crate) enum SendEventError {
-    #[error("the event receiver has closed")]
-    Closed,
-}
+#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
+#[error("the event receiver has closed")]
+pub(crate) struct SendEventError;
 
 #[must_use]
 pub(crate) fn transport_pair(
     client: Client,
     sync_service: Arc<SyncService>,
+    media: Arc<MediaService>,
     command_capacity: usize,
     event_capacity: usize,
 ) -> (ClientHandle, DriverPort, EventStream) {
-    let (command_tx, command_rx) = mpsc::channel(command_capacity);
+    let (request_tx, request_rx) = mpsc::channel(command_capacity);
     let (event_tx, event_rx) = mpsc::channel(event_capacity);
     let (connection_tx, connection_rx) = watch::channel(ConnectionState::Idle);
     (
         ClientHandle {
-            commands: command_tx,
-            next_id: Arc::new(AtomicU64::new(1)),
+            requests: request_tx,
             client,
             connection: connection_rx,
             notification_client: Arc::new(OnceCell::new()),
             sync_service,
+            media,
+            spaces: Arc::new(OnceCell::new()),
         },
         DriverPort {
-            commands: command_rx,
+            requests: request_rx,
             events: event_tx,
             connection: connection_tx,
         },
@@ -941,120 +1065,3 @@ fn normalise_push_notification(
         NotificationStatus::EventRedacted => PushNotificationStatus::Redacted,
     }
 }
-
-#[cfg(test)]
-mod tests {
-    use matrix_sdk::{Client, SessionMeta, SessionTokens, authentication::matrix::MatrixSession};
-
-    use crate::{ConnectionState, LifecycleCommand};
-
-    use super::*;
-
-    async fn sync_service(client: Client) -> Arc<SyncService> {
-        Arc::new(SyncService::builder(client).build().await.unwrap())
-    }
-
-    async fn test_client() -> Client {
-        let client = Client::builder()
-            .homeserver_url("http://localhost")
-            .build()
-            .await
-            .unwrap();
-        client
-            .restore_session(MatrixSession {
-                meta: SessionMeta {
-                    user_id: "@test:localhost".parse().unwrap(),
-                    device_id: "DEVICE".into(),
-                },
-                tokens: SessionTokens {
-                    access_token: "access_token".to_owned(),
-                    refresh_token: None,
-                },
-            })
-            .await
-            .unwrap();
-        client
-    }
-
-    #[tokio::test]
-    async fn transports_are_isolated() {
-        let first_client = test_client().await;
-        let second_client = test_client().await;
-        let (first_handle, mut first_driver, mut first_events) =
-            transport_pair(first_client.clone(), sync_service(first_client).await, 2, 2);
-        let (_second_handle, mut second_driver, mut second_events) = transport_pair(
-            second_client.clone(),
-            sync_service(second_client).await,
-            2,
-            2,
-        );
-
-        let id = first_handle
-            .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-            .await
-            .unwrap();
-        let request = first_driver.recv().await.unwrap();
-        assert!(matches!(
-            request,
-            DriverRequest::Command(CommandEnvelope {
-                id: received_id,
-                command: Command::Lifecycle(LifecycleCommand::Shutdown),
-            }) if received_id == id
-        ));
-        assert!(second_driver.commands.try_recv().is_err());
-
-        first_driver
-            .send(Event::ConnectionChanged(ConnectionState::Online))
-            .await
-            .unwrap();
-        assert_eq!(
-            first_events.recv().await,
-            Some(Event::ConnectionChanged(ConnectionState::Online))
-        );
-        assert!(second_events.try_recv().is_err());
-    }
-
-    #[tokio::test]
-    async fn bounded_command_channel_reports_pressure() {
-        let client = test_client().await;
-        let (handle, _driver, _events) =
-            transport_pair(client.clone(), sync_service(client).await, 1, 1);
-
-        handle
-            .try_send(Command::Lifecycle(LifecycleCommand::Shutdown))
-            .unwrap();
-        assert_eq!(
-            handle.try_send(Command::Lifecycle(LifecycleCommand::Shutdown)),
-            Err(SendCommandError::Full)
-        );
-    }
-
-    #[tokio::test]
-    async fn cloned_handles_share_command_id_sequence() {
-        let client = test_client().await;
-        let (handle, mut driver, _events) =
-            transport_pair(client.clone(), sync_service(client).await, 1, 1);
-        let cloned = handle.clone();
-        let first = handle
-            .try_send(Command::Lifecycle(LifecycleCommand::Shutdown))
-            .unwrap();
-        assert_eq!(first.get(), 1);
-        assert_eq!(
-            cloned.try_send(Command::Lifecycle(LifecycleCommand::Shutdown)),
-            Err(SendCommandError::Full)
-        );
-        driver.recv().await.unwrap();
-
-        let third = cloned
-            .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-            .await
-            .unwrap();
-        assert_eq!(third.get(), 3);
-        driver.recv().await.unwrap();
-
-        let fourth = handle
-            .try_send(Command::Lifecycle(LifecycleCommand::Shutdown))
-            .unwrap();
-        assert_eq!(fourth.get(), 4);
-    }
-}

Modified file: src/upload.rs+23 additions−22 deletions@@ -8,26 +8,26 @@ use matrix_sdk::{
     ruma::events::room::message::TextMessageEventContent,
 };
 
-use crate::{AttachmentUpload, CommandErrorKind, UploadDetails, error::CommandError};
+use crate::{AttachmentUpload, Error, ErrorKind, UploadDetails};
 
 pub(crate) fn prepare_upload(
     mut upload: AttachmentUpload,
     max_media_bytes: usize,
-) -> Result<(AttachmentUpload, mime::Mime, AttachmentConfig), CommandError> {
+) -> Result<(AttachmentUpload, mime::Mime, AttachmentConfig), Error> {
     if upload.bytes.len() > max_media_bytes {
-        return Err(CommandError::new(
-            CommandErrorKind::MediaTooLarge,
+        return Err(Error::new(
+            ErrorKind::MediaTooLarge,
             "attachment exceeds the configured byte limit",
         ));
     }
     let mimetype: mime::Mime = upload
         .mimetype
         .parse()
-        .map_err(|_| CommandError::new(CommandErrorKind::Other, "media MIME type is invalid"))?;
+        .map_err(|_| Error::new(ErrorKind::Invalid, "media MIME type is invalid"))?;
 
     let size = ruma::UInt::try_from(upload.bytes.len()).map_err(|_| {
-        CommandError::new(
-            CommandErrorKind::MediaTooLarge,
+        Error::new(
+            ErrorKind::MediaTooLarge,
             "attachment size is not representable",
         )
     })?;
@@ -67,8 +67,8 @@ pub(crate) fn prepare_upload(
             waveform,
         }) if mimetype.type_() == mime::AUDIO => {
             if waveform.iter().any(|sample| *sample > 1024) {
-                return Err(CommandError::new(
-                    CommandErrorKind::Other,
+                return Err(Error::new(
+                    ErrorKind::Invalid,
                     "voice waveform samples must be at most 1024",
                 ));
             }
@@ -106,15 +106,15 @@ pub(crate) fn prepare_upload(
             _ => AttachmentInfo::File(BaseFileInfo { size: Some(size) }),
         },
         _ => {
-            return Err(CommandError::new(
-                CommandErrorKind::Other,
+            return Err(Error::new(
+                ErrorKind::Invalid,
                 "attachment metadata does not match its MIME type",
             ));
         }
     };
     if upload.thumbnail.is_some() && mimetype.type_() == mime::AUDIO {
-        return Err(CommandError::new(
-            CommandErrorKind::MediaUnavailable,
+        return Err(Error::new(
+            ErrorKind::Invalid,
             "audio attachments do not support thumbnails",
         ));
     }
@@ -126,23 +126,24 @@ pub(crate) fn prepare_upload(
                 || thumbnail.width == 0
                 || thumbnail.height == 0
             {
-                return Err(CommandError::new(
-                    CommandErrorKind::MediaTooLarge,
+                return Err(Error::new(
+                    ErrorKind::MediaTooLarge,
                     "thumbnail size or dimensions are invalid",
                 ));
             }
-            let content_type: mime::Mime = thumbnail.mimetype.parse().map_err(|_| {
-                CommandError::new(CommandErrorKind::Other, "thumbnail MIME type is invalid")
-            })?;
+            let content_type: mime::Mime = thumbnail
+                .mimetype
+                .parse()
+                .map_err(|_| Error::new(ErrorKind::Invalid, "thumbnail MIME type is invalid"))?;
             if content_type.type_() != mime::IMAGE {
-                return Err(CommandError::new(
-                    CommandErrorKind::MediaUnavailable,
+                return Err(Error::new(
+                    ErrorKind::Invalid,
                     "thumbnail MIME type must be an image",
                 ));
             }
             let size = ruma::UInt::try_from(thumbnail.bytes.len()).map_err(|_| {
-                CommandError::new(
-                    CommandErrorKind::MediaTooLarge,
+                Error::new(
+                    ErrorKind::MediaTooLarge,
                     "thumbnail size is not representable",
                 )
             })?;

Modified file: tests/account.rs+16 additions−37 deletions@@ -1,10 +1,9 @@
 #![cfg(feature = "sqlite")]
-use std::time::{Duration, SystemTime};
+mod support;
 
-use macltok::{
-    Command, EngineConfig, Event, LifecycleCommand, PasswordLogin, Session, SessionRecord,
-    StoreConfig,
-};
+use std::time::SystemTime;
+
+use macltok::{EngineConfig, Event, PasswordLogin, Session, SessionRecord, StoreConfig};
 use matrix_sdk::{ruma::api::client::sync::sync_events::v5, test_utils::mocks::MatrixMockServer};
 
 #[tokio::test]
@@ -26,13 +25,8 @@ async fn password_session_round_trips_through_an_encrypted_store() {
     std::fs::create_dir_all(&store_path).unwrap();
     let config = EngineConfig::default().with_initial_history_limit(0);
     let session = Session::login_password(
-        PasswordLogin {
-            homeserver: server.uri(),
-            username: "example".into(),
-            password: "wordpass".into(),
-            device_display_name: Some("macltok test".into()),
-            device_id: None,
-        },
+        PasswordLogin::new(server.uri(), "example", "wordpass")
+            .with_device_display_name("macltok test"),
         StoreConfig::new(&store_path, "test store passphrase"),
     )
     .await
@@ -46,12 +40,11 @@ async fn password_session_round_trips_through_an_encrypted_store() {
 
     let (engine, handle, mut events) = session.build(config.clone()).await.unwrap();
     let running = tokio::spawn(engine.run());
-    receive_authenticated(&mut events).await;
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    running.await.unwrap().unwrap();
+    support::receive_until(&mut events, |event| {
+        matches!(event, Event::Authenticated { .. })
+    })
+    .await;
+    support::shut_down(&handle, &mut events, running).await;
 
     let session = Session::restore(
         record,
@@ -61,29 +54,15 @@ async fn password_session_round_trips_through_an_encrypted_store() {
     .unwrap();
     let (engine, handle, mut events) = session.build(config).await.unwrap();
     let running = tokio::spawn(engine.run());
-    receive_authenticated(&mut events).await;
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    running.await.unwrap().unwrap();
+    support::receive_until(&mut events, |event| {
+        matches!(event, Event::Authenticated { .. })
+    })
+    .await;
+    support::shut_down(&handle, &mut events, running).await;
 
     std::fs::remove_dir_all(store_path).unwrap();
 }
 
-async fn receive_authenticated(events: &mut macltok::EventStream) {
-    tokio::time::timeout(Duration::from_secs(2), async {
-        while let Some(event) = events.recv().await {
-            if matches!(event, Event::Authenticated { .. }) {
-                return;
-            }
-        }
-        panic!("event stream closed before authentication");
-    })
-    .await
-    .expect("authentication event did not arrive");
-}
-
 fn temporary_store_path() -> std::path::PathBuf {
     let nonce = SystemTime::now()
         .duration_since(SystemTime::UNIX_EPOCH)

Modified file: tests/commands.rs+68 additions−113 deletions@@ -1,18 +1,20 @@
+mod support;
+
 use std::time::Duration;
 
 use macltok::{
-    ClientHandle, Command, CommandErrorKind, CommandId, CommandKind, Engine, EngineConfig,
-    EngineError, Event, EventStream, LifecycleCommand, MessageContent, MessageEditContent,
-    RichText, RoomCommand, TimelineCommand,
+    ClientHandle, Command, Engine, EngineConfig, EngineError, ErrorKind, Event, EventStream,
+    MessageContent, MessageEditContent, RichText, RoomCommand, TimelineCommand,
 };
 use matrix_sdk::{
     ruma::{RoomId, api::client::sync::sync_events::v5, event_id, room_id},
     test_utils::mocks::MatrixMockServer,
 };
+use support::shut_down;
 use tokio::task::JoinHandle;
 
 #[tokio::test]
-async fn empty_message_bodies_report_their_command_ids() {
+async fn empty_message_bodies_fail_with_empty_body() {
     let room_id = room_id!("!empty-bodies:localhost");
     let (server, handle, mut events, running) = start_engine(room_id).await;
     open_room(&handle, &mut events, room_id).await;
@@ -42,14 +44,14 @@ async fn empty_message_bodies_report_their_command_ids() {
     ];
 
     for command in commands {
-        let id = handle.send(Command::Timeline(command)).await.unwrap();
-        let failure = receive_command_failure(&mut events, id).await;
-        assert_eq!(failure.id, id);
-        assert_eq!(failure.command, CommandKind::Timeline);
-        assert_eq!(failure.kind, CommandErrorKind::EmptyBody);
+        let error = handle
+            .execute(Command::Timeline(command))
+            .await
+            .expect_err("empty body command unexpectedly succeeded");
+        assert_eq!(error.kind, ErrorKind::EmptyBody);
     }
 
-    stop_engine(handle, &mut events, running).await;
+    shut_down(&handle, &mut events, running).await;
     drop(server);
 }
 
@@ -60,7 +62,7 @@ async fn open_resets_the_timeline_before_succeeding() {
 
     open_room(&handle, &mut events, room_id).await;
 
-    stop_engine(handle, &mut events, running).await;
+    shut_down(&handle, &mut events, running).await;
     drop(server);
 }
 
@@ -69,28 +71,56 @@ async fn same_room_sends_complete_in_submission_order() {
     let room_id = room_id!("!send-order:localhost");
     let (server, handle, mut events, running) = start_engine(room_id).await;
     open_room(&handle, &mut events, room_id).await;
+    server
+        .mock_room_send()
+        .ok(event_id!("$sent:localhost"))
+        .expect(2)
+        .mount()
+        .await;
 
-    let first_id = handle
-        .send(Command::Timeline(TimelineCommand::Send {
+    let first = handle
+        .try_send(Command::Timeline(TimelineCommand::Send {
             timeline_id: room_id.to_owned().into(),
             content: MessageContent::text("first"),
         }))
-        .await
         .unwrap();
-    let second_id = handle
-        .send(Command::Timeline(TimelineCommand::Send {
+    let second = handle
+        .try_send(Command::Timeline(TimelineCommand::Send {
             timeline_id: room_id.to_owned().into(),
             content: MessageContent::text("second"),
         }))
-        .await
         .unwrap();
 
-    assert_eq!(
-        receive_timeline_completion(&mut events, &[first_id, second_id]).await,
-        vec![first_id, second_id]
-    );
+    // both answers land almost together, so racing them can't show which was
+    // processed first, only the order the sends actually reached the homeserver can
+    let (first_result, second_result) = tokio::join!(first, second);
+    first_result.expect("first send failed");
+    second_result.expect("second send failed");
 
-    stop_engine(handle, &mut events, running).await;
+    tokio::time::timeout(Duration::from_secs(2), async {
+        loop {
+            let bodies: Vec<String> = server
+                .received_requests()
+                .await
+                .unwrap()
+                .iter()
+                .filter(|request| request.url.path().contains("/send/m.room.message/"))
+                .filter_map(|request| {
+                    serde_json::from_slice::<serde_json::Value>(&request.body).ok()
+                })
+                .filter_map(|body| body["body"].as_str().map(str::to_owned))
+                .collect();
+            if bodies.len() >= 2 {
+                assert_eq!(bodies, ["first", "second"]);
+                break;
+            }
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("both sends did not reach the homeserver in submission order");
+
+    shut_down(&handle, &mut events, running).await;
     drop(server);
 }
 
@@ -117,108 +147,33 @@ async fn start_engine(
     (server, handle, events, running)
 }
 
-async fn open_room(handle: &ClientHandle, events: &mut EventStream, room_id: &RoomId) -> CommandId {
-    let id = handle
+/// opens `room_id` and confirms its `TimelineReset` was already on the
+/// stream by the time the open command answered
+async fn open_room(handle: &ClientHandle, events: &mut EventStream, room_id: &RoomId) {
+    let mut pending = handle
         .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
         .await
         .unwrap();
     let mut reset_received = false;
-
     tokio::time::timeout(Duration::from_secs(2), async {
         loop {
-            match events.recv().await.expect("event stream closed") {
-                Event::TimelineReset {
-                    timeline_id: reset_timeline,
-                    ..
-                } if reset_timeline.room_id() == room_id => reset_received = true,
-                Event::CommandSucceeded {
-                    id: succeeded_id,
-                    command: CommandKind::Room,
-                } if succeeded_id == id => {
-                    assert!(reset_received);
-                    break;
+            tokio::select! {
+                biased;
+                event = events.recv() => {
+                    if let Event::TimelineReset { timeline_id, .. } = event.expect("event stream closed")
+                        && timeline_id.room_id() == room_id
+                    {
+                        reset_received = true;
+                    }
                 }
-                Event::CommandFailed(failure) if failure.id == id => {
-                    panic!("opening room failed {failure:?}")
-                }
-                _ => {}
-            }
-        }
-    })
-    .await
-    .expect("room did not open");
-    id
-}
-
-async fn receive_command_failure(
-    events: &mut EventStream,
-    expected_id: CommandId,
-) -> macltok::CommandFailure {
-    tokio::time::timeout(Duration::from_secs(2), async {
-        loop {
-            match events.recv().await.expect("event stream closed") {
-                Event::CommandFailed(failure) if failure.id == expected_id => return failure,
-                Event::CommandSucceeded { id, .. } if id == expected_id => {
-                    panic!("command unexpectedly succeeded")
-                }
-                _ => {}
-            }
-        }
-    })
-    .await
-    .expect("command failure did not arrive")
-}
-
-async fn receive_timeline_completion(
-    events: &mut EventStream,
-    expected_ids: &[CommandId],
-) -> Vec<CommandId> {
-    tokio::time::timeout(Duration::from_secs(2), async {
-        let mut completed = Vec::new();
-        while completed.len() < expected_ids.len() {
-            match events.recv().await.expect("event stream closed") {
-                Event::CommandSucceeded {
-                    id,
-                    command: CommandKind::Timeline,
-                } if expected_ids.contains(&id) => completed.push(id),
-                Event::CommandFailed(failure) if expected_ids.contains(&failure.id) => {
-                    panic!("timeline command failed {failure:?}")
-                }
-                _ => {}
-            }
-        }
-        completed
-    })
-    .await
-    .expect("timeline commands did not complete")
-}
-
-async fn stop_engine(
-    handle: ClientHandle,
-    events: &mut EventStream,
-    running: JoinHandle<Result<(), EngineError>>,
-) {
-    let id = handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    tokio::time::timeout(Duration::from_secs(2), async {
-        let mut succeeded = false;
-        while let Some(event) = events.recv().await {
-            match event {
-                Event::CommandSucceeded {
-                    id: succeeded_id,
-                    command: CommandKind::Lifecycle,
-                } if succeeded_id == id => succeeded = true,
-                Event::Stopped => {
-                    assert!(succeeded);
+                result = &mut pending => {
+                    result.expect("opening room failed");
                     break;
                 }
-                _ => {}
             }
         }
     })
     .await
-    .expect("engine did not stop");
-    running.await.unwrap().unwrap();
+    .expect("room did not open");
+    assert!(reset_received, "open completed before its reset");
 }

Modified file: tests/engine.rs+162 additions−267 deletions@@ -1,15 +1,17 @@
+mod support;
+
 use std::time::Duration;
 
 use macltok::{
-    Command, CommandErrorKind, Engine, EngineConfig, Event, HistoryState, LifecycleCommand,
-    MediaCommand, MessageContent, RoomCommand, TimelineCommand, TimelineDiff, TimelineId,
-    TimelineItem,
+    ClientHandle, Command, Engine, EngineConfig, ErrorKind, Event, EventStream, HistoryState,
+    MediaSize, MessageContent, RoomCommand, TimelineCommand, TimelineId, TimelineItem,
 };
 use matrix_sdk::{
     ruma::{api::client::sync::sync_events::v5, event_id, mxc_uri, room_id},
     test_utils::mocks::{MatrixMockServer, RoomMessagesResponseTemplate},
 };
 use matrix_sdk_test::{ALICE, JoinedRoomBuilder, event_factory::EventFactory};
+use support::{event_messages, receive_until, shut_down};
 
 #[tokio::test]
 async fn opens_a_room_and_sends_messages() {
@@ -36,10 +38,7 @@ async fn opens_a_room_and_sends_messages() {
     let (engine, handle, mut events) = Engine::from_client(client, config).await.unwrap();
     let running = tokio::spawn(engine.run());
 
-    handle
-        .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
-        .await
-        .unwrap();
+    handle.open_room(room_id.to_owned()).await.unwrap();
     receive_until(
         &mut events,
         |event| matches!(event, Event::TimelineReset { timeline_id: reset, .. } if reset.room_id() == room_id),
@@ -47,10 +46,10 @@ async fn opens_a_room_and_sends_messages() {
     .await;
 
     handle
-        .send(Command::Timeline(TimelineCommand::Send {
-            timeline_id: room_id.to_owned().into(),
-            content: MessageContent::text("hello from macltok"),
-        }))
+        .send_message(
+            room_id.to_owned().into(),
+            MessageContent::text("hello from macltok"),
+        )
         .await
         .unwrap();
     tokio::time::timeout(Duration::from_secs(2), async {
@@ -90,31 +89,19 @@ async fn opens_a_room_and_sends_messages() {
         )
         .await;
     let media_event = receive_until(&mut events, |event| {
-        event_messages(event).any(|message| message.media.is_some())
+        event_messages(event)
+            .into_iter()
+            .any(|message| message.media.is_some())
     })
     .await;
     let media_id = event_messages(&media_event)
+        .into_iter()
         .find_map(|message| message.media.as_ref().map(|media| media.id.clone()))
         .unwrap();
-    handle
-        .send(Command::Media(MediaCommand::Fetch {
-            id: media_id.clone(),
-            size: macltok::MediaSize::Full,
-        }))
-        .await
-        .unwrap();
-    let media = receive_until(&mut events, |event| {
-        matches!(event, Event::MediaReady { media_id: received, .. } if received == &media_id)
-    })
-    .await;
-    assert!(matches!(media, Event::MediaReady { bytes, .. } if !bytes.is_empty()));
+    let media = handle.media(&media_id, MediaSize::Full).await.unwrap();
+    assert!(!media.bytes.is_empty());
 
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
-    running.await.unwrap().unwrap();
+    shut_down(&handle, &mut events, running).await;
 }
 
 #[tokio::test]
@@ -136,14 +123,12 @@ async fn keeps_open_room_timelines_independent() {
     let (engine, handle, mut events) = Engine::from_client(client, config).await.unwrap();
     let running = tokio::spawn(engine.run());
 
-    handle
-        .send(Command::Room(RoomCommand::Open(first_id.to_owned())))
-        .await
-        .unwrap();
-    handle
-        .send(Command::Room(RoomCommand::Open(second_id.to_owned())))
-        .await
-        .unwrap();
+    let (first_open, second_open) = tokio::join!(
+        handle.open_room(first_id.to_owned()),
+        handle.open_room(second_id.to_owned())
+    );
+    first_open.unwrap();
+    second_open.unwrap();
     receive_until(
         &mut events,
         |event| matches!(event, Event::TimelineReset { timeline_id, .. } if timeline_id.room_id() == first_id),
@@ -179,19 +164,20 @@ async fn keeps_open_room_timelines_independent() {
             let event = events.recv().await.expect("event stream closed");
             if let Event::TimelineChanged { timeline_id, .. } = &event {
                 first_updated |= timeline_id.room_id() == first_id
-                    && event_messages(&event).any(|message| message.body == "first update");
+                    && event_messages(&event)
+                        .into_iter()
+                        .any(|message| message.body == "first update");
                 second_updated |= timeline_id.room_id() == second_id
-                    && event_messages(&event).any(|message| message.body == "second update");
+                    && event_messages(&event)
+                        .into_iter()
+                        .any(|message| message.body == "second update");
             }
         }
     })
     .await
     .expect("both retained rooms did not update");
 
-    handle
-        .send(Command::Room(RoomCommand::Close(first_id.to_owned())))
-        .await
-        .unwrap();
+    handle.close_room(first_id.to_owned()).await.unwrap();
     server
         .sync_room(
             &sync_client,
@@ -201,16 +187,13 @@ async fn keeps_open_room_timelines_independent() {
         .await;
     receive_until(&mut events, |event| {
         matches!(event, Event::TimelineChanged { timeline_id, .. } if timeline_id.room_id() == second_id)
-            && event_messages(event).any(|message| message.body == "still live")
+            && event_messages(event)
+                .into_iter()
+                .any(|message| message.body == "still live")
     })
     .await;
 
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
-    running.await.unwrap().unwrap();
+    shut_down(&handle, &mut events, running).await;
 }
 
 #[tokio::test]
@@ -230,10 +213,7 @@ async fn resync_replaces_timeline_before_ack_and_preserves_following_diffs() {
     let (engine, handle, mut events) = Engine::from_client(client, config).await.unwrap();
     let running = tokio::spawn(engine.run());
 
-    handle
-        .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
-        .await
-        .unwrap();
+    handle.open_room(room_id.to_owned()).await.unwrap();
     receive_until(&mut events, |event| {
         matches!(event,
             Event::TimelineReset { timeline_id, .. } if timeline_id.room_id() == room_id
@@ -248,37 +228,14 @@ async fn resync_replaces_timeline_before_ack_and_preserves_following_diffs() {
         )
         .await;
     receive_until(&mut events, |event| {
-        event_messages(event).any(|message| message.body == "before reset")
+        event_messages(event)
+            .into_iter()
+            .any(|message| message.body == "before reset")
     })
     .await;
 
-    let id = handle
-        .send(Command::Timeline(TimelineCommand::Resync {
-            timeline_id: room_id.to_owned().into(),
-        }))
-        .await
-        .unwrap();
-    let mut reset = None;
-    tokio::time::timeout(Duration::from_secs(2), async {
-        loop {
-            match events.recv().await.expect("event stream closed") {
-                Event::TimelineReset { timeline_id, items } if timeline_id.room_id() == room_id => {
-                    reset = Some(items);
-                }
-                Event::CommandSucceeded { id: completed, .. } if completed == id => {
-                    assert!(reset.is_some(), "resync completed before its reset");
-                    break;
-                }
-                Event::CommandFailed(failure) if failure.id == id => {
-                    panic!("resync failed: {failure:?}")
-                }
-                _ => {}
-            }
-        }
-    })
-    .await
-    .expect("resync did not complete");
-    let mut items = reset.unwrap();
+    let mut items =
+        resync_and_confirm_reset_first(&handle, &mut events, room_id.to_owned().into()).await;
     assert!(items.iter().any(|item| matches!(item,
         TimelineItem::Message(message) if message.body == "before reset"
     )));
@@ -313,12 +270,7 @@ async fn resync_replaces_timeline_before_ack_and_preserves_following_diffs() {
     .await
     .expect("resynced timeline did not update");
 
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
-    running.await.unwrap().unwrap();
+    shut_down(&handle, &mut events, running).await;
 }
 
 #[tokio::test]
@@ -337,76 +289,76 @@ async fn closes_and_reopens_a_room_in_command_order() {
     let (engine, handle, mut events) = Engine::from_client(client, config).await.unwrap();
     let running = tokio::spawn(engine.run());
 
-    let initial_open = handle
-        .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
-        .await
-        .unwrap();
+    handle.open_room(room_id.to_owned()).await.unwrap();
     receive_until(
         &mut events,
         |event| matches!(event, Event::TimelineReset { timeline_id, .. } if timeline_id.room_id() == room_id),
     )
     .await;
-    receive_until(
-        &mut events,
-        |event| matches!(event, Event::CommandSucceeded { id, .. } if id == &initial_open),
-    )
-    .await;
 
-    let close = handle
-        .send(Command::Room(RoomCommand::Close(room_id.to_owned())))
-        .await
+    let mut close = handle
+        .try_send(Command::Room(RoomCommand::Close(room_id.to_owned())))
         .unwrap();
-    let replacement_open = handle
-        .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
-        .await
+    let mut replacement_open = handle
+        .try_send(Command::Room(RoomCommand::Open(room_id.to_owned())))
         .unwrap();
-    let second_close = handle
-        .send(Command::Room(RoomCommand::Close(room_id.to_owned())))
-        .await
+    let mut second_close = handle
+        .try_send(Command::Room(RoomCommand::Close(room_id.to_owned())))
         .unwrap();
-    let final_open = handle
-        .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
-        .await
+    let mut final_open = handle
+        .try_send(Command::Room(RoomCommand::Open(room_id.to_owned())))
         .unwrap();
-    let expected = [close, replacement_open, second_close, final_open];
-    let mut completed = 0;
+
+    // biased select drains every buffered reset before it ever reports a ready reply,
+    // so the engine can race ahead and land both resets before either open is observed
     let mut resets = 0;
+    let mut order = Vec::new();
+    let (mut close_done, mut replacement_open_done, mut second_close_done, mut final_open_done) =
+        (false, false, false, false);
     tokio::time::timeout(Duration::from_secs(3), async {
-        while completed < expected.len() {
-            match events.recv().await.expect("event stream closed") {
-                Event::TimelineReset { timeline_id, .. } if timeline_id.room_id() == room_id => {
-                    resets += 1;
-                    assert!(resets <= 2, "a room generation reset more than once");
-                }
-                Event::CommandSucceeded { id, .. } if expected.contains(&id) => {
-                    assert_eq!(
-                        id, expected[completed],
-                        "room lifecycle commands completed out of order"
-                    );
-                    if completed == 1 || completed == 3 {
-                        assert_eq!(
-                            resets,
-                            completed / 2 + 1,
-                            "room open completed before timeline reset"
-                        );
+        while order.len() < 4 {
+            tokio::select! {
+                biased;
+                event = events.recv() => {
+                    if let Event::TimelineReset { timeline_id, .. } = event.expect("event stream closed")
+                        && timeline_id.room_id() == room_id
+                    {
+                        resets += 1;
+                        assert!(resets <= 2, "a room generation reset more than once");
                     }
-                    completed += 1;
                 }
-                Event::CommandFailed(failure) if expected.contains(&failure.id) => {
-                    panic!("room lifecycle command failed: {failure:?}");
+                result = &mut close, if !close_done => {
+                    result.expect("close failed");
+                    close_done = true;
+                    order.push("close");
+                }
+                result = &mut replacement_open, if !replacement_open_done => {
+                    result.expect("replacement open failed");
+                    replacement_open_done = true;
+                    order.push("replacement_open");
+                }
+                result = &mut second_close, if !second_close_done => {
+                    result.expect("second close failed");
+                    second_close_done = true;
+                    order.push("second_close");
+                }
+                result = &mut final_open, if !final_open_done => {
+                    result.expect("final open failed");
+                    final_open_done = true;
+                    order.push("final_open");
                 }
-                _ => {}
             }
         }
     })
     .await
     .expect("room lifecycle commands did not complete");
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
-    running.await.unwrap().unwrap();
+    assert_eq!(
+        order,
+        ["close", "replacement_open", "second_close", "final_open"]
+    );
+    assert_eq!(resets, 2, "each open should have reset the timeline once");
+
+    shut_down(&handle, &mut events, running).await;
 }
 
 #[tokio::test]
@@ -429,83 +381,50 @@ async fn thread_command_waits_for_opening_timeline() {
     .await
     .unwrap();
     let running = tokio::spawn(engine.run());
-    let room_open = handle
-        .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
-        .await
-        .unwrap();
-    receive_until(
-        &mut events,
-        |event| matches!(event, Event::CommandSucceeded { id, .. } if *id == room_open),
-    )
-    .await;
+    handle.open_room(room_id.to_owned()).await.unwrap();
 
-    let open = handle
-        .send(Command::Timeline(TimelineCommand::OpenThread {
+    let mut open = handle
+        .try_send(Command::Timeline(TimelineCommand::OpenThread {
             room_id: room_id.to_owned(),
             root_event_id: root.to_owned(),
         }))
-        .await
         .unwrap();
-    let send = handle
-        .send(Command::Timeline(TimelineCommand::Send {
+    let mut send = handle
+        .try_send(Command::Timeline(TimelineCommand::Send {
             timeline_id: TimelineId::thread(room_id.to_owned(), root.to_owned()),
             content: MessageContent::text(""),
         }))
-        .await
-        .unwrap();
-    let resync = handle
-        .send(Command::Timeline(TimelineCommand::Resync {
-            timeline_id: TimelineId::thread(room_id.to_owned(), root.to_owned()),
-        }))
-        .await
         .unwrap();
     let mut open_succeeded = false;
+    let mut send_done = false;
     tokio::time::timeout(Duration::from_secs(3), async {
-        loop {
-            match events.recv().await.expect("event stream closed") {
-                Event::CommandSucceeded { id, .. } if id == open => open_succeeded = true,
-                Event::CommandFailed(failure) if failure.id == send => {
-                    assert!(open_succeeded, "thread command completed before opening");
-                    assert_eq!(failure.kind, CommandErrorKind::EmptyBody);
-                    break;
+        while !send_done {
+            tokio::select! {
+                biased;
+                result = &mut open, if !open_succeeded => {
+                    result.expect("thread open failed");
+                    open_succeeded = true;
                 }
-                Event::CommandFailed(failure) if failure.id == open => {
-                    panic!("thread open failed: {failure:?}");
+                result = &mut send, if !send_done => {
+                    assert!(open_succeeded, "thread command completed before opening");
+                    let error = result.expect_err("empty body send unexpectedly succeeded");
+                    assert_eq!(error.kind, ErrorKind::EmptyBody);
+                    send_done = true;
                 }
-                _ => {}
             }
         }
     })
     .await
     .expect("thread commands did not complete");
-    let mut reset_seen = false;
-    tokio::time::timeout(Duration::from_secs(3), async {
-        loop {
-            match events.recv().await.expect("event stream closed") {
-                Event::TimelineReset { timeline_id, .. }
-                    if timeline_id.thread_root().is_some_and(|event| event == root) =>
-                {
-                    reset_seen = true
-                }
-                Event::CommandSucceeded { id, .. } if id == resync => {
-                    assert!(reset_seen, "thread resync completed before its reset");
-                    break;
-                }
-                Event::CommandFailed(failure) if failure.id == resync => {
-                    panic!("thread resync failed: {failure:?}")
-                }
-                _ => {}
-            }
-        }
-    })
-    .await
-    .expect("thread resync did not complete");
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
-    running.await.unwrap().unwrap();
+
+    resync_and_confirm_reset_first(
+        &handle,
+        &mut events,
+        TimelineId::thread(room_id.to_owned(), root.to_owned()),
+    )
+    .await;
+
+    shut_down(&handle, &mut events, running).await;
 }
 
 #[tokio::test]
@@ -525,10 +444,7 @@ async fn pagination_reports_and_remembers_start_of_history() {
     let (engine, handle, mut events) = Engine::from_client(client, config).await.unwrap();
     let running = tokio::spawn(engine.run());
 
-    handle
-        .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
-        .await
-        .unwrap();
+    handle.open_room(room_id.to_owned()).await.unwrap();
     receive_until(
         &mut events,
         |event| matches!(event, Event::TimelineReset { timeline_id: reset, .. } if reset.room_id() == room_id),
@@ -546,7 +462,9 @@ async fn pagination_reports_and_remembers_start_of_history() {
         .await;
     receive_until(&mut events, |event| {
         matches!(event, Event::TimelineChanged { timeline_id: changed, .. } if changed.room_id() == room_id)
-            && event_messages(event).any(|message| message.body == "latest")
+            && event_messages(event)
+                .into_iter()
+                .any(|message| message.body == "latest")
     })
     .await;
 
@@ -560,10 +478,7 @@ async fn pagination_reports_and_remembers_start_of_history() {
     let mut reached_start = false;
     for _ in 0..3 {
         handle
-            .send(Command::Timeline(TimelineCommand::Paginate {
-                timeline_id: room_id.to_owned().into(),
-                limit: 10,
-            }))
+            .paginate(room_id.to_owned().into(), 10)
             .await
             .unwrap();
         receive_history(&mut events, room_id, HistoryState::Loading).await;
@@ -582,24 +497,54 @@ async fn pagination_reports_and_remembers_start_of_history() {
     );
 
     handle
-        .send(Command::Timeline(TimelineCommand::Paginate {
-            timeline_id: room_id.to_owned().into(),
-            limit: 10,
-        }))
+        .paginate(room_id.to_owned().into(), 10)
         .await
         .unwrap();
     receive_history(&mut events, room_id, HistoryState::StartReached).await;
 
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
+    shut_down(&handle, &mut events, running).await;
+}
+
+/// resyncs `timeline_id` and confirms its `TimelineReset` was already on the
+/// stream by the time the resync command answered, racing the two so we
+/// don't have to drain the whole stream first
+async fn resync_and_confirm_reset_first(
+    handle: &ClientHandle,
+    events: &mut EventStream,
+    timeline_id: TimelineId,
+) -> Vec<TimelineItem> {
+    let mut pending = handle
+        .send(Command::Timeline(TimelineCommand::Resync {
+            timeline_id: timeline_id.clone(),
+        }))
         .await
         .unwrap();
-    receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
-    running.await.unwrap().unwrap();
+    let mut reset_items = None;
+    tokio::time::timeout(Duration::from_secs(3), async {
+        loop {
+            tokio::select! {
+                biased;
+                event = events.recv() => {
+                    if let Event::TimelineReset { timeline_id: reset_id, items } = event.expect("event stream closed")
+                        && reset_id == timeline_id
+                    {
+                        reset_items = Some(items);
+                    }
+                }
+                result = &mut pending => {
+                    result.expect("resync failed");
+                    break;
+                }
+            }
+        }
+    })
+    .await
+    .expect("resync did not complete");
+    reset_items.expect("resync completed before its reset")
 }
 
 async fn receive_history(
-    events: &mut macltok::EventStream,
+    events: &mut EventStream,
     room_id: &matrix_sdk::ruma::RoomId,
     expected: HistoryState,
 ) {
@@ -609,42 +554,8 @@ async fn receive_history(
     .await;
 }
 
-fn event_messages(event: &Event) -> std::vec::IntoIter<&macltok::TimelineMessage> {
-    let items = match event {
-        Event::TimelineReset { items, .. } => items.iter().collect::<Vec<_>>(),
-        Event::TimelineChanged { diffs, .. } => {
-            diffs.iter().flat_map(diff_items).collect::<Vec<_>>()
-        }
-        _ => Vec::new(),
-    };
-    items
-        .into_iter()
-        .filter_map(|item| match item {
-            TimelineItem::Message(message) => Some(message.as_ref()),
-            _ => None,
-        })
-        .collect::<Vec<_>>()
-        .into_iter()
-}
-
-fn diff_items(diff: &TimelineDiff) -> Vec<&TimelineItem> {
-    match diff {
-        TimelineDiff::Append { values } | TimelineDiff::Reset { values } => values.iter().collect(),
-        TimelineDiff::PushFront { value }
-        | TimelineDiff::PushBack { value }
-        | TimelineDiff::Insert { value, .. }
-        | TimelineDiff::Set { value, .. } => vec![value],
-        TimelineDiff::Clear
-        | TimelineDiff::PopFront
-        | TimelineDiff::PopBack
-        | TimelineDiff::Remove { .. }
-        | TimelineDiff::Truncate { .. } => Vec::new(),
-        _ => Vec::new(),
-    }
-}
-
 async fn receive_history_terminal(
-    events: &mut macltok::EventStream,
+    events: &mut EventStream,
     room_id: &matrix_sdk::ruma::RoomId,
 ) -> HistoryState {
     match receive_until(events, |event| {
@@ -690,19 +601,3 @@ async fn wait_for_room_subscriptions(
     .await
     .expect("Sliding Sync did not retain every open room subscription");
 }
-
-async fn receive_until(
-    events: &mut macltok::EventStream,
-    predicate: impl Fn(&Event) -> bool,
-) -> Event {
-    tokio::time::timeout(Duration::from_secs(2), async {
-        while let Some(event) = events.recv().await {
-            if predicate(&event) {
-                return event;
-            }
-        }
-        panic!("event stream closed before the expected event");
-    })
-    .await
-    .expect("expected event did not arrive")
-}

Modified file: tests/media.rs+114 additions−294 deletions@@ -1,9 +1,10 @@
+mod support;
+
 use std::{sync::Arc, time::Duration};
 
 use macltok::{
-    AttachmentUpload, ClientHandle, Command, CommandErrorKind, Engine, EngineConfig, EngineError,
-    Event, EventStream, LifecycleCommand, MediaCommand, MediaId, MediaSize, RoomCommand,
-    TimelineDiff, TimelineItem, UploadDetails, UploadThumbnail,
+    AttachmentUpload, ClientHandle, Engine, EngineConfig, EngineError, ErrorKind, Event,
+    EventStream, MediaId, MediaSize, UploadDetails, UploadThumbnail,
 };
 use matrix_sdk::{
     media::{MediaFormat, MediaRequestParameters},
@@ -43,7 +44,7 @@ async fn full_size_uses_full_source() {
     let mut harness = start(file_with_thumbnail()).await;
     mount_downloads(&harness.server).await;
 
-    let bytes = fetch_ready(&mut harness, MediaSize::Full).await;
+    let bytes = fetch(&harness, MediaSize::Full).await;
     assert_eq!(&*bytes, b"binaryjpegfullimagedata");
     assert!(
         media_paths(&harness.server)
@@ -52,7 +53,7 @@ async fn full_size_uses_full_source() {
             .any(|path| path.ends_with("/localhost/full"))
     );
 
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -94,13 +95,10 @@ async fn encrypted_media_is_cached_as_plaintext_like_the_sdk_does() {
         .await
         .unwrap();
     assert_eq!(from_sdk, plaintext);
-    assert_eq!(
-        &*fetch_ready(&mut harness, MediaSize::Full).await,
-        &plaintext[..]
-    );
+    assert_eq!(&*fetch(&harness, MediaSize::Full).await, &plaintext[..]);
     assert_eq!(media_paths(&harness.server).await.len(), 1);
 
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -116,42 +114,17 @@ async fn simultaneous_fetches_share_one_download() {
         .mount(harness.server.server())
         .await;
 
-    let mut pending = Vec::new();
-    for _ in 0..2 {
-        pending.push(
-            harness
-                .handle
-                .send(Command::Media(MediaCommand::Fetch {
-                    id: harness.media_id.clone(),
-                    size: MediaSize::Full,
-                }))
-                .await
-                .unwrap(),
-        );
-    }
-    let mut ready = false;
-    tokio::time::timeout(Duration::from_secs(5), async {
-        loop {
-            match harness.events.recv().await.expect("event stream closed") {
-                Event::MediaReady {
-                    media_id, bytes, ..
-                } if media_id == harness.media_id => {
-                    assert_eq!(&*bytes, b"shared image bytes");
-                    ready = true;
-                }
-                Event::CommandSucceeded { id, .. } => pending.retain(|waiting| *waiting != id),
-                Event::CommandFailed(failure) if pending.contains(&failure.id) => {
-                    panic!("fetch failed: {failure:?}");
-                }
-                _ => {}
-            }
-            if ready && pending.is_empty() {
-                break;
-            }
-        }
+    let (first, second) = tokio::time::timeout(Duration::from_secs(5), async {
+        tokio::join!(
+            harness.handle.media(&harness.media_id, MediaSize::Full),
+            harness.handle.media(&harness.media_id, MediaSize::Full),
+        )
     })
     .await
     .expect("both fetches did not complete");
+    assert_eq!(&*first.unwrap().bytes, b"shared image bytes");
+    assert_eq!(&*second.unwrap().bytes, b"shared image bytes");
+
     let downloads = harness
         .server
         .received_requests()
@@ -161,7 +134,7 @@ async fn simultaneous_fetches_share_one_download() {
         .filter(|request| request.url.path().ends_with("/download/localhost/image"))
         .count();
     assert_eq!(downloads, 1, "duplicate in-flight media download");
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -178,19 +151,15 @@ async fn downloaded_media_over_limit_is_rejected() {
         .respond_with(ResponseTemplate::new(200).set_body_bytes(b"too large".to_vec()))
         .mount(harness.server.server())
         .await;
-    let id = harness
+
+    let error = harness
         .handle
-        .send(Command::Media(MediaCommand::Fetch {
-            id: harness.media_id.clone(),
-            size: MediaSize::Full,
-        }))
+        .media(&harness.media_id, MediaSize::Full)
         .await
-        .unwrap();
-    receive_until(&mut harness.events, |event| {
-        matches!(event, Event::CommandFailed(failure) if failure.id == id && failure.kind == CommandErrorKind::MediaTooLarge)
-    })
-    .await;
-    stop(harness).await;
+        .unwrap_err();
+    assert_eq!(error.kind, ErrorKind::MediaTooLarge);
+
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -198,7 +167,7 @@ async fn thumbnail_size_prefers_explicit_thumbnail() {
     let mut harness = start(file_with_thumbnail()).await;
     mount_downloads(&harness.server).await;
 
-    let bytes = fetch_ready(&mut harness, MediaSize::Thumbnail).await;
+    let bytes = fetch(&harness, thumbnail_size()).await;
     assert_eq!(&*bytes, b"binaryjpegfullimagedata");
     let paths = media_paths(&harness.server).await;
     assert!(
@@ -208,7 +177,7 @@ async fn thumbnail_size_prefers_explicit_thumbnail() {
     );
     assert!(!paths.iter().any(|path| path.ends_with("/localhost/full")));
 
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -227,7 +196,7 @@ async fn plain_image_thumbnail_uses_thumbnail_endpoint() {
         .mount()
         .await;
 
-    let bytes = fetch_ready(&mut harness, MediaSize::Thumbnail).await;
+    let bytes = fetch(&harness, thumbnail_size()).await;
     assert_eq!(&*bytes, b"binaryjpegthumbnaildata");
     assert!(
         media_paths(&harness.server)
@@ -236,36 +205,21 @@ async fn plain_image_thumbnail_uses_thumbnail_endpoint() {
             .any(|path| path.contains("/thumbnail/localhost/image"))
     );
 
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
-async fn unavailable_thumbnail_reports_returned_command_id() {
+async fn audio_thumbnail_fetch_fails_with_media_unavailable() {
     let mut harness = start(plain_audio()).await;
-    let command_id = harness
+
+    let error = harness
         .handle
-        .send(Command::Media(MediaCommand::Fetch {
-            id: harness.media_id.clone(),
-            size: MediaSize::Thumbnail,
-        }))
+        .media(&harness.media_id, thumbnail_size())
         .await
-        .unwrap();
+        .unwrap_err();
+    assert_eq!(error.kind, ErrorKind::MediaUnavailable);
 
-    let event = receive_until(&mut harness.events, |event| {
-        matches!(
-            event,
-            Event::CommandFailed(failure)
-                if failure.id == command_id && failure.kind == CommandErrorKind::MediaUnavailable
-        )
-    })
-    .await;
-    assert!(matches!(
-        event,
-        Event::CommandFailed(failure)
-            if failure.id == command_id && failure.kind == CommandErrorKind::MediaUnavailable
-    ));
-
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -293,22 +247,14 @@ async fn media_upload_is_queued_and_sent() {
         .mount()
         .await;
 
-    let id = harness
-        .handle
-        .upload_media(
-            room_id!("!media:localhost").to_owned().into(),
-            "photo.jpg".to_owned(),
-            "image/jpeg".to_owned(),
-            b"photo data".to_vec(),
-            Some("holiday".to_owned()),
-        )
-        .await
-        .unwrap();
-    receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::CommandSucceeded { id: completed, .. } if *completed == id),
-    )
-    .await;
+    let mut upload = AttachmentUpload::new(
+        room_id!("!media:localhost").to_owned(),
+        "photo.jpg",
+        "image/jpeg",
+        b"photo data".to_vec(),
+    );
+    upload.caption = Some("holiday".to_owned());
+    harness.handle.upload(upload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(5), async {
         loop {
@@ -325,7 +271,7 @@ async fn media_upload_is_queued_and_sent() {
     .await
     .expect("queued media was not sent");
 
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -344,9 +290,9 @@ async fn queued_offline_attachment_exposes_fetchable_local_media() {
         height: Some(16),
         blurhash: None,
     });
-    harness.handle.upload_attachment(upload).await.unwrap();
-    let event = receive_until(&mut harness.events, |event| {
-        event_messages(event).any(|message| {
+    harness.handle.upload(upload).await.unwrap();
+    let event = support::receive_until(&mut harness.events, |event| {
+        support::event_messages(event).into_iter().any(|message| {
             message.own
                 && message.transaction_id.is_some()
                 && message
@@ -356,7 +302,8 @@ async fn queued_offline_attachment_exposes_fetchable_local_media() {
         })
     })
     .await;
-    let media = event_messages(&event)
+    let media = support::event_messages(&event)
+        .into_iter()
         .find(|message| message.own && message.media.is_some())
         .and_then(|message| message.media.as_ref())
         .unwrap();
@@ -364,26 +311,14 @@ async fn queued_offline_attachment_exposes_fetchable_local_media() {
     assert_eq!(media.size_bytes, Some(original.len() as u64));
     let media_id = media.id.clone();
 
-    let fetch_id = harness
+    let fetched = harness
         .handle
-        .send(Command::Media(MediaCommand::Fetch {
-            id: media_id.clone(),
-            size: MediaSize::Full,
-        }))
+        .media(&media_id, MediaSize::Full)
         .await
         .unwrap();
-    let ready = receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::MediaReady { media_id: id, .. } if id == &media_id),
-    )
-    .await;
-    assert!(matches!(ready, Event::MediaReady { bytes, .. } if *bytes == original));
-    receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::CommandSucceeded { id, .. } if *id == fetch_id),
-    )
-    .await;
-    stop(harness).await;
+    assert_eq!(&*fetched.bytes, &original[..]);
+
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -431,18 +366,13 @@ async fn image_upload_uses_caller_supplied_metadata_and_thumbnail() {
         height: Some(450),
         blurhash: None,
     });
-    upload.thumbnail = Some(UploadThumbnail {
-        bytes: thumbnail_bytes.clone(),
-        mimetype: "image/png".to_owned(),
-        width: 800,
-        height: 400,
-    });
-    let id = harness.handle.upload_attachment(upload).await.unwrap();
-    receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::CommandSucceeded { id: completed, .. } if *completed == id),
-    )
-    .await;
+    upload.thumbnail = Some(UploadThumbnail::new(
+        thumbnail_bytes.clone(),
+        "image/png",
+        800,
+        400,
+    ));
+    harness.handle.upload(upload).await.unwrap();
 
     let content = uploaded_content(&harness.server).await;
     assert_eq!(content["msgtype"], "m.image");
@@ -475,7 +405,7 @@ async fn image_upload_uses_caller_supplied_metadata_and_thumbnail() {
             .any(|request| request.body == thumbnail_bytes)
     );
 
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -523,18 +453,13 @@ async fn video_upload_preserves_metadata_and_supplied_thumbnail() {
         duration_ms: Some(3500),
         blurhash: Some("blurhash".to_owned()),
     });
-    upload.thumbnail = Some(UploadThumbnail {
-        bytes: b"poster bytes".to_vec(),
-        mimetype: "image/png".to_owned(),
-        width: 320,
-        height: 180,
-    });
-    let id = harness.handle.upload_attachment(upload).await.unwrap();
-    receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::CommandSucceeded { id: completed, .. } if *completed == id),
-    )
-    .await;
+    upload.thumbnail = Some(UploadThumbnail::new(
+        b"poster bytes".to_vec(),
+        "image/png",
+        320,
+        180,
+    ));
+    harness.handle.upload(upload).await.unwrap();
 
     let content = uploaded_content(&harness.server).await;
     assert_eq!(content["msgtype"], "m.video");
@@ -556,7 +481,7 @@ async fn video_upload_preserves_metadata_and_supplied_thumbnail() {
         request.url.path().ends_with("/_matrix/media/v3/upload") && request.body == b"poster bytes"
     }));
 
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -599,12 +524,7 @@ async fn voice_upload_emits_voice_details_and_correlated_progress() {
         duration_ms: 4200,
         waveform: vec![0, 512, 1024],
     });
-    let id = harness.handle.upload_attachment(upload).await.unwrap();
-    receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::CommandSucceeded { id: completed, .. } if *completed == id),
-    )
-    .await;
+    harness.handle.upload(upload).await.unwrap();
 
     let pending = harness
         .handle
@@ -613,7 +533,7 @@ async fn voice_upload_emits_voice_details_and_correlated_progress() {
         .unwrap();
     assert_eq!(pending.len(), 1);
     let transaction_id = pending[0].clone();
-    let progress = receive_until(&mut harness.events, |event| {
+    let progress = support::receive_until(&mut harness.events, |event| {
         matches!(event, Event::MediaUploadProgress { transaction_id: seen, complete: true, .. } if seen == &transaction_id)
     })
     .await;
@@ -636,7 +556,7 @@ async fn voice_upload_emits_voice_details_and_correlated_progress() {
     );
     assert_eq!(content["org.matrix.msc3245.voice"], json!({}));
 
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -653,15 +573,8 @@ async fn mismatched_upload_metadata_and_invalid_waveform_fail_without_uploading(
         height: Some(32),
         blurhash: None,
     });
-    let id = harness.handle.upload_attachment(mismatched).await.unwrap();
-    let failure = receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::CommandFailed(failure) if failure.id == id),
-    )
-    .await;
-    assert!(
-        matches!(failure, Event::CommandFailed(failure) if failure.kind == CommandErrorKind::Other)
-    );
+    let error = harness.handle.upload(mismatched).await.unwrap_err();
+    assert_eq!(error.kind, ErrorKind::Invalid);
 
     let mut voice = AttachmentUpload::new(
         room_id!("!media:localhost").to_owned(),
@@ -673,15 +586,8 @@ async fn mismatched_upload_metadata_and_invalid_waveform_fail_without_uploading(
         duration_ms: 1000,
         waveform: vec![1025],
     });
-    let id = harness.handle.upload_attachment(voice).await.unwrap();
-    let failure = receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::CommandFailed(failure) if failure.id == id),
-    )
-    .await;
-    assert!(
-        matches!(failure, Event::CommandFailed(failure) if failure.kind == CommandErrorKind::Other)
-    );
+    let error = harness.handle.upload(voice).await.unwrap_err();
+    assert_eq!(error.kind, ErrorKind::Invalid);
 
     assert!(
         !harness
@@ -692,7 +598,7 @@ async fn mismatched_upload_metadata_and_invalid_waveform_fail_without_uploading(
             .iter()
             .any(|request| { request.url.path().ends_with("/_matrix/media/v3/upload") })
     );
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -710,16 +616,8 @@ async fn upload_over_media_limit_fails_without_uploading() {
         "application/octet-stream",
         b"too large".to_vec(),
     );
-    let id = harness.handle.upload_attachment(upload).await.unwrap();
-    let failure = receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::CommandFailed(failure) if failure.id == id),
-    )
-    .await;
-    assert!(matches!(
-        failure,
-        Event::CommandFailed(failure) if failure.kind == CommandErrorKind::MediaTooLarge
-    ));
+    let error = harness.handle.upload(upload).await.unwrap_err();
+    assert_eq!(error.kind, ErrorKind::MediaTooLarge);
     assert!(
         !harness
             .server
@@ -729,7 +627,7 @@ async fn upload_over_media_limit_fails_without_uploading() {
             .iter()
             .any(|request| { request.url.path().ends_with("/_matrix/media/v3/upload") })
     );
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
@@ -741,22 +639,14 @@ async fn audio_thumbnail_fails_without_uploading() {
         "audio/ogg",
         b"voice bytes".to_vec(),
     );
-    upload.thumbnail = Some(UploadThumbnail {
-        bytes: b"thumbnail".to_vec(),
-        mimetype: "image/png".to_owned(),
-        width: 80,
-        height: 80,
-    });
-    let id = harness.handle.upload_attachment(upload).await.unwrap();
-    let failure = receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::CommandFailed(failure) if failure.id == id),
-    )
-    .await;
-    assert!(matches!(
-        failure,
-        Event::CommandFailed(failure) if failure.kind == CommandErrorKind::MediaUnavailable
+    upload.thumbnail = Some(UploadThumbnail::new(
+        b"thumbnail".to_vec(),
+        "image/png",
+        80,
+        80,
     ));
+    let error = harness.handle.upload(upload).await.unwrap_err();
+    assert_eq!(error.kind, ErrorKind::Invalid);
     assert!(
         !harness
             .server
@@ -766,33 +656,22 @@ async fn audio_thumbnail_fails_without_uploading() {
             .iter()
             .any(|request| { request.url.path().ends_with("/_matrix/media/v3/upload") })
     );
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 #[tokio::test]
-async fn invalid_upload_mime_reports_a_command_failure() {
+async fn invalid_upload_mime_fails_without_uploading() {
     let mut harness = start(plain_image()).await;
-    let id = harness
-        .handle
-        .upload_media(
-            room_id!("!media:localhost").to_owned().into(),
-            "photo.jpg".to_owned(),
-            "not a MIME type".to_owned(),
-            b"photo data".to_vec(),
-            None,
-        )
-        .await
-        .unwrap();
-    let event = receive_until(
-        &mut harness.events,
-        |event| matches!(event, Event::CommandFailed(failure) if failure.id == id),
-    )
-    .await;
-    assert!(
-        matches!(event, Event::CommandFailed(failure) if failure.kind == CommandErrorKind::Other)
+    let upload = AttachmentUpload::new(
+        room_id!("!media:localhost").to_owned(),
+        "photo.jpg",
+        "not a MIME type",
+        b"photo data".to_vec(),
     );
+    let error = harness.handle.upload(upload).await.unwrap_err();
+    assert_eq!(error.kind, ErrorKind::Invalid);
 
-    stop(harness).await;
+    support::shut_down(&harness.handle, &mut harness.events, harness.running).await;
 }
 
 async fn start(content: RoomMessageEventContent) -> MediaHarness {
@@ -818,11 +697,8 @@ async fn start_with_config(content: RoomMessageEventContent, config: EngineConfi
     let (engine, handle, mut events) = Engine::from_client(client, config).await.unwrap();
     let running = tokio::spawn(engine.run());
 
-    handle
-        .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
-        .await
-        .unwrap();
-    receive_until(
+    handle.open_room(room_id.to_owned()).await.unwrap();
+    support::receive_until(
         &mut events,
         |event| matches!(event, Event::TimelineReset { timeline_id: reset, .. } if reset.room_id() == room_id),
     )
@@ -835,11 +711,14 @@ async fn start_with_config(content: RoomMessageEventContent, config: EngineConfi
                 .add_timeline_event(EventFactory::new().event(content).sender(&ALICE)),
         )
         .await;
-    let event = receive_until(&mut events, |event| {
-        event_messages(event).any(|message| message.media.is_some())
+    let event = support::receive_until(&mut events, |event| {
+        support::event_messages(event)
+            .into_iter()
+            .any(|message| message.media.is_some())
     })
     .await;
-    let media_id = event_messages(&event)
+    let media_id = support::event_messages(&event)
+        .into_iter()
         .find_map(|message| message.media.as_ref().map(|media| media.id.clone()))
         .unwrap();
 
@@ -858,37 +737,20 @@ async fn mount_downloads(server: &MatrixMockServer) {
     server.mock_authed_media_download().ok_image().mount().await;
 }
 
-async fn fetch_ready(harness: &mut MediaHarness, size: MediaSize) -> Arc<[u8]> {
-    harness
-        .handle
-        .send(Command::Media(MediaCommand::Fetch {
-            id: harness.media_id.clone(),
-            size,
-        }))
-        .await
-        .unwrap();
-    match receive_until(&mut harness.events, |event| {
-        matches!(
-            event,
-            Event::MediaReady { media_id, size: received, .. }
-                if media_id == &harness.media_id && received == &size
-        )
-    })
-    .await
-    {
-        Event::MediaReady { bytes, .. } => bytes,
-        _ => unreachable!(),
+fn thumbnail_size() -> MediaSize {
+    MediaSize::Thumbnail {
+        width: 800,
+        height: 800,
     }
 }
 
-async fn stop(mut harness: MediaHarness) {
+async fn fetch(harness: &MediaHarness, size: MediaSize) -> Arc<[u8]> {
     harness
         .handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
+        .media(&harness.media_id, size)
         .await
-        .unwrap();
-    receive_until(&mut harness.events, |event| matches!(event, Event::Stopped)).await;
-    harness.running.await.unwrap().unwrap();
+        .unwrap()
+        .bytes
 }
 
 async fn media_paths(server: &MatrixMockServer) -> Vec<String> {
@@ -948,45 +810,3 @@ fn plain_audio() -> RoomMessageEventContent {
         mxc_uri!("mxc://localhost/audio").to_owned(),
     )))
 }
-
-fn event_messages(event: &Event) -> std::vec::IntoIter<&macltok::TimelineMessage> {
-    let items = match event {
-        Event::TimelineReset { items, .. } => items.iter().collect::<Vec<_>>(),
-        Event::TimelineChanged { diffs, .. } => {
-            diffs.iter().flat_map(diff_items).collect::<Vec<_>>()
-        }
-        _ => Vec::new(),
-    };
-    items
-        .into_iter()
-        .filter_map(|item| match item {
-            TimelineItem::Message(message) => Some(message.as_ref()),
-            _ => None,
-        })
-        .collect::<Vec<_>>()
-        .into_iter()
-}
-
-fn diff_items(diff: &TimelineDiff) -> Vec<&TimelineItem> {
-    match diff {
-        TimelineDiff::Append { values } | TimelineDiff::Reset { values } => values.iter().collect(),
-        TimelineDiff::PushFront { value }
-        | TimelineDiff::PushBack { value }
-        | TimelineDiff::Insert { value, .. }
-        | TimelineDiff::Set { value, .. } => vec![value],
-        _ => Vec::new(),
-    }
-}
-
-async fn receive_until(events: &mut EventStream, predicate: impl Fn(&Event) -> bool) -> Event {
-    tokio::time::timeout(Duration::from_secs(5), async {
-        while let Some(event) = events.recv().await {
-            if predicate(&event) {
-                return event;
-            }
-        }
-        panic!("event stream closed before the expected event");
-    })
-    .await
-    .expect("expected event did not arrive")
-}

Modified file: tests/members.rs+9 additions−5 deletions@@ -1,4 +1,4 @@
-use macltok::{ClientQueryError, Engine, EngineConfig, MemberFilter, MemberMembership};
+use macltok::{Engine, EngineConfig, ErrorKind, MemberFilter, MemberMembership};
 use matrix_sdk::{
     ruma::{
         api::client::sync::sync_events::v5, events::room::member::MembershipState, room_id, user_id,
@@ -191,10 +191,14 @@ async fn members_rejects_unknown_room() {
         .unwrap();
     let room_id = room_id!("!missing:localhost");
 
-    assert!(matches!(
-        handle.members(room_id, MemberFilter::All).await,
-        Err(ClientQueryError::RoomUnknown(missing)) if missing == room_id
-    ));
+    assert_eq!(
+        handle
+            .members(room_id, MemberFilter::All)
+            .await
+            .unwrap_err()
+            .kind,
+        ErrorKind::RoomUnknown
+    );
 
     drop(engine);
 }

Modified file: tests/nonblocking.rs+30 additions−110 deletions@@ -1,15 +1,16 @@
+mod support;
+
 use std::time::Duration;
 
 use macltok::{
-    Command, CommandErrorKind, CommandKind, Engine, EngineConfig, Event, LifecycleCommand,
-    MediaCommand, MediaSize, MessageContent, RoomCommand, TimelineCommand, TimelineDiff,
-    TimelineItem,
+    Command, Engine, EngineConfig, ErrorKind, Event, MediaSize, MessageContent, TimelineCommand,
 };
 use matrix_sdk::{
     ruma::{api::client::sync::sync_events::v5, mxc_uri, room_id},
     test_utils::mocks::MatrixMockServer,
 };
 use matrix_sdk_test::{ALICE, JoinedRoomBuilder, event_factory::EventFactory};
+use support::{event_messages, receive_until, shut_down};
 use wiremock::ResponseTemplate;
 
 #[tokio::test]
@@ -29,10 +30,7 @@ async fn delayed_media_fetch_does_not_block_timeline_command() {
     let (engine, handle, mut events) = Engine::from_client(client, config).await.unwrap();
     let running = tokio::spawn(engine.run());
 
-    handle
-        .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
-        .await
-        .unwrap();
+    handle.open_room(room_id.to_owned()).await.unwrap();
     receive_until(
         &mut events,
         |event| matches!(event, Event::TimelineReset { timeline_id: reset, .. } if reset.room_id() == room_id),
@@ -53,10 +51,13 @@ async fn delayed_media_fetch_does_not_block_timeline_command() {
         )
         .await;
     let media_event = receive_until(&mut events, |event| {
-        event_messages(event).any(|message| message.media.is_some())
+        event_messages(event)
+            .into_iter()
+            .any(|message| message.media.is_some())
     })
     .await;
     let media_id = event_messages(&media_event)
+        .into_iter()
         .find_map(|message| message.media.as_ref().map(|media| media.id.clone()))
         .unwrap();
 
@@ -76,65 +77,34 @@ async fn delayed_media_fetch_does_not_block_timeline_command() {
         .mount()
         .await;
 
-    let media_command_id = handle
-        .send(Command::Media(MediaCommand::Fetch {
-            id: media_id.clone(),
-            size: MediaSize::Full,
-        }))
-        .await
-        .unwrap();
+    // media no longer travels through the command queue, so driving it on its
+    // own task is what puts the request in flight concurrently with the send below
+    let media_task = tokio::spawn({
+        let handle = handle.clone();
+        async move { handle.media(&media_id, MediaSize::Full).await }
+    });
     wait_for_media_request(&server).await;
-    let timeline_command_id = handle
-        .send(Command::Timeline(TimelineCommand::Send {
+
+    let error = tokio::time::timeout(
+        Duration::from_millis(300),
+        handle.execute(Command::Timeline(TimelineCommand::Send {
             timeline_id: room_id.to_owned().into(),
             content: MessageContent::text(String::new()),
-        }))
-        .await
-        .unwrap();
-
-    tokio::time::timeout(Duration::from_secs(2), async {
-        loop {
-            match events.recv().await.expect("event stream closed") {
-                Event::CommandFailed(failure) if failure.id == timeline_command_id => {
-                    assert_eq!(failure.command, CommandKind::Timeline);
-                    assert_eq!(failure.kind, CommandErrorKind::EmptyBody);
-                    break;
-                }
-                Event::CommandSucceeded { id, .. } if id == media_command_id => {
-                    panic!("media command completed before the timeline command")
-                }
-                Event::CommandFailed(failure) if failure.id == media_command_id => {
-                    panic!("media command failed before the timeline command {failure:?}")
-                }
-                Event::MediaReady {
-                    media_id: ready_id, ..
-                } if ready_id == media_id => {
-                    panic!("media became ready before the timeline command completed")
-                }
-                _ => {}
-            }
-        }
-    })
+        })),
+    )
     .await
-    .expect("timeline command was blocked by media fetch");
-
-    receive_until(&mut events, |event| {
-        matches!(
-            event,
-            Event::CommandSucceeded {
-                id,
-                command: CommandKind::Media,
-            } if id == &media_command_id
-        )
-    })
-    .await;
+    .expect("timeline command was blocked by media fetch")
+    .expect_err("empty body command unexpectedly succeeded");
+    assert_eq!(error.kind, ErrorKind::EmptyBody);
 
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
+    let media = tokio::time::timeout(Duration::from_secs(2), media_task)
         .await
+        .expect("media fetch did not complete")
+        .unwrap()
         .unwrap();
-    receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
-    running.await.unwrap().unwrap();
+    assert!(!media.bytes.is_empty());
+
+    shut_down(&handle, &mut events, running).await;
 }
 
 async fn wait_for_media_request(server: &MatrixMockServer) {
@@ -155,53 +125,3 @@ async fn wait_for_media_request(server: &MatrixMockServer) {
     .await
     .expect("media request did not reach the homeserver");
 }
-
-fn event_messages(event: &Event) -> std::vec::IntoIter<&macltok::TimelineMessage> {
-    let items = match event {
-        Event::TimelineReset { items, .. } => items.iter().collect::<Vec<_>>(),
-        Event::TimelineChanged { diffs, .. } => {
-            diffs.iter().flat_map(diff_items).collect::<Vec<_>>()
-        }
-        _ => Vec::new(),
-    };
-    items
-        .into_iter()
-        .filter_map(|item| match item {
-            TimelineItem::Message(message) => Some(message.as_ref()),
-            _ => None,
-        })
-        .collect::<Vec<_>>()
-        .into_iter()
-}
-
-fn diff_items(diff: &TimelineDiff) -> Vec<&TimelineItem> {
-    match diff {
-        TimelineDiff::Append { values } | TimelineDiff::Reset { values } => values.iter().collect(),
-        TimelineDiff::PushFront { value }
-        | TimelineDiff::PushBack { value }
-        | TimelineDiff::Insert { value, .. }
-        | TimelineDiff::Set { value, .. } => vec![value],
-        TimelineDiff::Clear
-        | TimelineDiff::PopFront
-        | TimelineDiff::PopBack
-        | TimelineDiff::Remove { .. }
-        | TimelineDiff::Truncate { .. } => Vec::new(),
-        _ => Vec::new(),
-    }
-}
-
-async fn receive_until(
-    events: &mut macltok::EventStream,
-    predicate: impl Fn(&Event) -> bool,
-) -> Event {
-    tokio::time::timeout(Duration::from_secs(2), async {
-        while let Some(event) = events.recv().await {
-            if predicate(&event) {
-                return event;
-            }
-        }
-        panic!("event stream closed before the expected event")
-    })
-    .await
-    .expect("expected event did not arrive")
-}

Modified file: tests/send_queue.rs+43 additions−107 deletions@@ -1,8 +1,9 @@
+mod support;
+
 use std::time::Duration;
 
 use macltok::{
-    ClientHandle, Command, CommandErrorKind, CommandId, CommandKind, Engine, EngineConfig, Event,
-    EventStream, LifecycleCommand, MessageContent, RoomCommand, TimelineCommand, TimelineItem,
+    AttachmentUpload, ClientHandle, Engine, EngineConfig, ErrorKind, EventStream, MessageContent,
 };
 use matrix_sdk::{
     Client,
@@ -24,11 +25,10 @@ async fn cancel_send_uses_transaction_id_from_public_timeline() {
             .unwrap()
             .contains(&transaction_id)
     );
-    let id = handle
+    handle
         .cancel_send(room_id.to_owned(), transaction_id.clone())
         .await
         .unwrap();
-    expect_success(&mut events, id, CommandKind::Room).await;
 
     let (echoes, _) = client
         .get_room(room_id)
@@ -43,20 +43,13 @@ async fn cancel_send_uses_transaction_id_from_public_timeline() {
             .any(|echo| echo.transaction_id == transaction_id)
     );
 
-    let id = handle
+    let error = handle
         .cancel_send(room_id.to_owned(), transaction_id)
         .await
-        .unwrap();
-    let failure = receive_until(
-        &mut events,
-        |event| matches!(event, Event::CommandFailed(failure) if failure.id == id),
-    )
-    .await;
-    assert!(
-        matches!(failure, Event::CommandFailed(failure) if failure.kind == CommandErrorKind::Other)
-    );
+        .unwrap_err();
+    assert_eq!(error.kind, ErrorKind::Invalid);
 
-    stop(handle, &mut events, running).await;
+    support::shut_down(&handle, &mut events, running).await;
     drop(server);
 }
 
@@ -66,28 +59,25 @@ async fn cancel_queued_attachment_by_pending_send_id() {
     let room_id = room_id!("!queue-controls:localhost");
     client.send_queue().set_enabled(false).await;
 
-    let id = handle
-        .upload_media(
-            room_id.to_owned().into(),
-            "note.txt".to_owned(),
-            "text/plain".to_owned(),
+    handle
+        .upload(AttachmentUpload::new(
+            room_id.to_owned(),
+            "note.txt",
+            "text/plain",
             b"attachment".to_vec(),
-            None,
-        )
+        ))
         .await
         .unwrap();
-    expect_success(&mut events, id, CommandKind::Media).await;
 
     let pending = handle.pending_send_ids(room_id).await.unwrap();
     assert_eq!(pending.len(), 1);
-    let id = handle
+    handle
         .cancel_send(room_id.to_owned(), pending[0].clone())
         .await
         .unwrap();
-    expect_success(&mut events, id, CommandKind::Room).await;
     assert!(handle.pending_send_ids(room_id).await.unwrap().is_empty());
 
-    stop(handle, &mut events, running).await;
+    support::shut_down(&handle, &mut events, running).await;
     drop(server);
 }
 
@@ -109,11 +99,10 @@ async fn retry_send_wakes_paused_queue() {
         .await;
 
     let transaction_id = queue_message(&handle, &mut events, room_id, "retry me").await;
-    let id = handle
+    handle
         .retry_send(room_id.to_owned(), transaction_id)
         .await
         .unwrap();
-    expect_success(&mut events, id, CommandKind::Room).await;
     assert!(client.get_room(room_id).unwrap().send_queue().is_enabled());
 
     tokio::time::timeout(Duration::from_secs(5), async {
@@ -134,7 +123,7 @@ async fn retry_send_wakes_paused_queue() {
     .await
     .expect("retried message was not sent");
 
-    stop(handle, &mut events, running).await;
+    support::shut_down(&handle, &mut events, running).await;
     drop(server);
 }
 
@@ -155,101 +144,48 @@ async fn setup() -> (
     let room_id = room_id!("!queue-controls:localhost");
     server.mock_room_state_encryption().plain().mount().await;
     server.sync_joined_room(&client, room_id).await;
-    let (engine, handle, events) = Engine::from_client(
+    let (engine, handle, mut events) = Engine::from_client(
         client.clone(),
         EngineConfig::default().with_initial_history_limit(0),
     )
     .await
     .unwrap();
     let running = tokio::spawn(engine.run());
-    let mut events = events;
-    let id = handle
-        .send(Command::Room(RoomCommand::Open(room_id.to_owned())))
+    let (opened, _) = tokio::join!(handle.open_room(room_id.to_owned()), async {
+        support::receive_until(&mut events, |event| {
+            matches!(event, macltok::Event::TimelineReset { .. })
+        })
         .await
-        .unwrap();
-    expect_success(&mut events, id, CommandKind::Room).await;
+    });
+    opened.unwrap();
     (server, client, handle, events, running)
 }
 
+/// sends a message and waits for its local echo, since only the timeline reveals the transaction id
 async fn queue_message(
     handle: &ClientHandle,
     events: &mut EventStream,
     room_id: &RoomId,
     body: &str,
 ) -> OwnedTransactionId {
-    let id = handle
-        .send(Command::Timeline(TimelineCommand::Send {
-            timeline_id: room_id.to_owned().into(),
-            content: MessageContent::text(body),
-        }))
-        .await
-        .unwrap();
-    let mut succeeded = false;
-    let mut items = Vec::new();
-    tokio::time::timeout(Duration::from_secs(5), async {
-        loop {
-            match events.recv().await.expect("event stream closed") {
-                Event::TimelineChanged { diffs, .. } => {
-                    for diff in diffs {
-                        diff.try_apply(&mut items).unwrap();
-                    }
-                    let transaction = items.iter().find_map(|item| match item {
-                        TimelineItem::Message(message) if message.body == body => {
-                            message.transaction_id.clone()
-                        }
-                        _ => None,
-                    });
-                    if let Some(transaction) = transaction {
-                        if !succeeded {
-                            expect_success(events, id, CommandKind::Timeline).await;
-                        }
-                        return transaction;
-                    }
+    let send = handle.send_message(room_id.to_owned().into(), MessageContent::text(body));
+    let wait_for_echo = async {
+        tokio::time::timeout(Duration::from_secs(5), async {
+            loop {
+                let event = events.recv().await.expect("event stream closed");
+                let transaction = support::event_messages(&event)
+                    .into_iter()
+                    .find(|message| message.body == body)
+                    .and_then(|message| message.transaction_id.clone());
+                if let Some(transaction) = transaction {
+                    return transaction;
                 }
-                Event::CommandSucceeded {
-                    id: completed,
-                    command: CommandKind::Timeline,
-                } if completed == id => succeeded = true,
-                Event::CommandFailed(failure) if failure.id == id => {
-                    panic!("send failed {failure:?}")
-                }
-                _ => {}
-            }
-        }
-    })
-    .await
-    .expect("local echo did not appear")
-}
-
-async fn expect_success(events: &mut EventStream, id: CommandId, command: CommandKind) {
-    receive_until(events, |event| {
-        matches!(event, Event::CommandSucceeded { id: completed, command: kind } if *completed == id && *kind == command)
-    })
-    .await;
-}
-
-async fn receive_until(events: &mut EventStream, predicate: impl Fn(&Event) -> bool) -> Event {
-    tokio::time::timeout(Duration::from_secs(5), async {
-        loop {
-            let event = events.recv().await.expect("event stream closed");
-            if predicate(&event) {
-                return event;
             }
-        }
-    })
-    .await
-    .expect("expected event did not arrive")
-}
-
-async fn stop(
-    handle: ClientHandle,
-    events: &mut EventStream,
-    running: tokio::task::JoinHandle<Result<(), macltok::EngineError>>,
-) {
-    let id = handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
+        })
         .await
-        .unwrap();
-    expect_success(events, id, CommandKind::Lifecycle).await;
-    running.await.unwrap().unwrap();
+        .expect("local echo did not appear")
+    };
+    let (result, transaction_id) = tokio::join!(send, wait_for_echo);
+    result.unwrap();
+    transaction_id
 }

Modified file: tests/state.rs+11 additions−38 deletions@@ -1,9 +1,8 @@
+mod support;
+
 use std::time::Duration;
 
-use macltok::{
-    Command, ConnectionState, Engine, EngineConfig, EngineError, Event, LifecycleCommand,
-    RoomMembership,
-};
+use macltok::{ConnectionState, Engine, EngineConfig, EngineError, Event, RoomMembership};
 use matrix_sdk::{
     ruma::{api::client::sync::sync_events::v5, room_id},
     test_utils::mocks::MatrixMockServer,
@@ -26,7 +25,7 @@ async fn rooms_changed_invalidates_room_summaries() {
     let (engine, handle, mut events) = Engine::from_client(client, config).await.unwrap();
     let running = tokio::spawn(engine.run());
 
-    receive_until(&mut events, |event| matches!(event, Event::RoomsChanged)).await;
+    support::receive_until(&mut events, |event| matches!(event, Event::RoomsChanged)).await;
     let rooms = handle.rooms().await;
     let summary = rooms
         .iter()
@@ -35,12 +34,7 @@ async fn rooms_changed_invalidates_room_summaries() {
     assert_eq!(summary.membership, RoomMembership::Joined);
     assert!(!summary.name.is_empty());
 
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
-    running.await.unwrap().unwrap();
+    support::shut_down(&handle, &mut events, running).await;
 }
 
 #[tokio::test]
@@ -60,24 +54,19 @@ async fn connection_watch_tracks_the_engine_lifecycle() {
     assert_eq!(*connection_peer.borrow(), ConnectionState::Idle);
 
     let running = tokio::spawn(engine.run());
-    receive_until(&mut events, |event| {
+    support::receive_until(&mut events, |event| {
         matches!(event, Event::ConnectionChanged(ConnectionState::Connecting))
     })
     .await;
     assert_ne!(*connection.borrow(), ConnectionState::Idle);
-    receive_until(&mut events, |event| {
+    support::receive_until(&mut events, |event| {
         matches!(event, Event::ConnectionChanged(ConnectionState::Online))
     })
     .await;
     wait_for_connection(&mut connection, ConnectionState::Online).await;
     assert_eq!(*connection_peer.borrow(), ConnectionState::Online);
 
-    handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
-    running.await.unwrap().unwrap();
+    support::shut_down(&handle, &mut events, running).await;
     wait_for_connection(&mut connection, ConnectionState::Stopped).await;
     assert_eq!(*connection_peer.borrow(), ConnectionState::Stopped);
 }
@@ -98,11 +87,11 @@ async fn soft_logout_says_so_and_stops_the_engine() {
     .await
     .unwrap();
     let running = tokio::spawn(engine.run());
-    receive_until(&mut events, |event| {
+    support::receive_until(&mut events, |event| {
         matches!(event, Event::SessionAccessRejected { soft_logout: true })
     })
     .await;
-    receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
+    support::receive_until(&mut events, |event| matches!(event, Event::Stopped)).await;
     running.await.unwrap().unwrap();
 }
 
@@ -122,7 +111,7 @@ async fn closing_the_event_stream_stops_an_idle_engine() {
     .await
     .unwrap();
     let running = tokio::spawn(engine.run());
-    receive_until(&mut events, |event| {
+    support::receive_until(&mut events, |event| {
         matches!(event, Event::ConnectionChanged(ConnectionState::Online))
     })
     .await;
@@ -153,19 +142,3 @@ async fn wait_for_connection(
     .await
     .expect("expected connection state did not arrive");
 }
-
-async fn receive_until(
-    events: &mut macltok::EventStream,
-    predicate: impl Fn(&Event) -> bool,
-) -> Event {
-    tokio::time::timeout(Duration::from_secs(2), async {
-        while let Some(event) = events.recv().await {
-            if predicate(&event) {
-                return event;
-            }
-        }
-        panic!("event stream closed before the expected event");
-    })
-    .await
-    .expect("expected event did not arrive")
-}

Added file: tests/support/mod.rs+57 additions@@ -0,0 +1,57 @@
+#![allow(dead_code)]
+
+use std::time::Duration;
+
+use macltok::{ClientHandle, Event, EventStream, TimelineDiff, TimelineItem, TimelineMessage};
+
+pub async fn receive_until(events: &mut EventStream, predicate: impl Fn(&Event) -> bool) -> Event {
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while let Some(event) = events.recv().await {
+            if predicate(&event) {
+                return event;
+            }
+        }
+        panic!("event stream closed before the expected event");
+    })
+    .await
+    .expect("expected event did not arrive")
+}
+
+/// asks for a shutdown while still draining, since the engine won't answer until its events are out
+pub async fn shut_down(
+    handle: &ClientHandle,
+    events: &mut EventStream,
+    running: tokio::task::JoinHandle<Result<(), macltok::EngineError>>,
+) {
+    let (answer, _) = tokio::join!(handle.shutdown(), async {
+        receive_until(events, |event| matches!(event, Event::Stopped)).await
+    });
+    answer.unwrap();
+    running.await.unwrap().unwrap();
+}
+
+pub fn event_messages(event: &Event) -> Vec<&TimelineMessage> {
+    let items = match event {
+        Event::TimelineReset { items, .. } => items.iter().collect::<Vec<_>>(),
+        Event::TimelineChanged { diffs, .. } => diffs.iter().flat_map(diff_items).collect(),
+        _ => Vec::new(),
+    };
+    items
+        .into_iter()
+        .filter_map(|item| match item {
+            TimelineItem::Message(message) => Some(message.as_ref()),
+            _ => None,
+        })
+        .collect()
+}
+
+pub fn diff_items(diff: &TimelineDiff) -> Vec<&TimelineItem> {
+    match diff {
+        TimelineDiff::Append { values } | TimelineDiff::Reset { values } => values.iter().collect(),
+        TimelineDiff::PushFront { value }
+        | TimelineDiff::PushBack { value }
+        | TimelineDiff::Insert { value, .. }
+        | TimelineDiff::Set { value, .. } => vec![value],
+        _ => Vec::new(),
+    }
+}

Modified file: tests/tier0.rs+76 additions−126 deletions@@ -1,9 +1,8 @@
-use std::time::Duration;
+mod support;
 
 use macltok::{
-    ClientHandle, ClientQueryError, Command, CommandErrorKind, CommandId, CommandKind,
-    CreateRoomOptions, Engine, EngineConfig, EngineError, Event, EventStream, LifecycleCommand,
-    RoomCommand, RoomPreset, RoomVisibility,
+    ClientHandle, CreateRoomOptions, Engine, EngineConfig, EngineError, ErrorKind, EventStream,
+    RoomPreset, RoomVisibility,
 };
 use matrix_sdk::{
     ruma::{
@@ -43,11 +42,11 @@ async fn joining_by_room_id_forwards_via_servers() {
         .await
         .unwrap();
     assert_eq!(joined_room, room_id);
-    stop_engine(handle, &mut events, running).await;
+    support::shut_down(&handle, &mut events, running).await;
 }
 
 #[tokio::test]
-async fn leave_and_forget_report_correlated_success() {
+async fn leaving_then_forgetting_a_room_hits_the_expected_endpoints() {
     let room_id = room_id!("!leave:localhost");
     let (server, client) = configured_client().await;
     server.sync_joined_room(&client, room_id).await;
@@ -55,15 +54,11 @@ async fn leave_and_forget_report_correlated_success() {
     server.mock_room_forget().ok().expect(1).mount().await;
     let (handle, mut events, running) = run_client(client).await;
 
-    let leave_id = handle.leave_room(room_id.to_owned()).await.unwrap();
-    receive_room_success(&mut events, leave_id).await;
-    let forget_id = handle
-        .send(Command::Room(RoomCommand::Forget(room_id.to_owned())))
-        .await
-        .unwrap();
-    receive_room_success(&mut events, forget_id).await;
-    assert_ne!(leave_id, forget_id);
-    stop_engine(handle, &mut events, running).await;
+    handle.leave_room(room_id.to_owned()).await.unwrap();
+    handle.forget_room(room_id.to_owned()).await.unwrap();
+
+    support::shut_down(&handle, &mut events, running).await;
+    drop(server);
 }
 
 #[tokio::test]
@@ -86,11 +81,10 @@ async fn accepting_and_rejecting_invites_use_the_expected_endpoints() {
         .await;
     let (handle, mut events, running) = run_client(client).await;
 
-    let accept_id = handle.accept_invite(accepted.to_owned()).await.unwrap();
-    receive_room_success(&mut events, accept_id).await;
-    let reject_id = handle.reject_invite(rejected.to_owned()).await.unwrap();
-    receive_room_success(&mut events, reject_id).await;
-    stop_engine(handle, &mut events, running).await;
+    handle.accept_invite(accepted.to_owned()).await.unwrap();
+    handle.reject_invite(rejected.to_owned()).await.unwrap();
+
+    support::shut_down(&handle, &mut events, running).await;
 }
 
 #[tokio::test]
@@ -114,19 +108,19 @@ async fn creating_a_room_forwards_options() {
         .await;
 
     let created_room = handle
-        .create_room(CreateRoomOptions {
-            name: Some("Planning".to_owned()),
-            topic: Some("Next release".to_owned()),
-            alias_localpart: Some("planning".to_owned()),
-            invite: vec![user_id!("@partner:localhost").to_owned()],
-            visibility: RoomVisibility::Public,
-            preset: Some(RoomPreset::PublicChat),
-            ..Default::default()
-        })
+        .create_room(
+            CreateRoomOptions::default()
+                .with_name("Planning")
+                .with_topic("Next release")
+                .with_alias_localpart("planning")
+                .with_invite(vec![user_id!("@partner:localhost").to_owned()])
+                .with_visibility(RoomVisibility::Public)
+                .with_preset(RoomPreset::PublicChat),
+        )
         .await
         .unwrap();
     assert_eq!(created_room, room_id!("!created:localhost").to_owned());
-    stop_engine(handle, &mut events, running).await;
+    support::shut_down(&handle, &mut events, running).await;
 }
 
 #[tokio::test]
@@ -167,23 +161,48 @@ async fn creating_a_direct_room_invites_the_other_user() {
         .await
         .unwrap();
     assert_eq!(direct_room, room_id!("!direct:localhost").to_owned());
-    stop_engine(handle, &mut events, running).await;
+    support::shut_down(&handle, &mut events, running).await;
 }
 
 #[tokio::test]
-async fn unknown_rooms_fail_membership_commands_with_their_ids() {
+async fn unknown_rooms_fail_membership_commands_with_room_unknown() {
     let (server, handle, mut events, running) = start_engine().await;
     let unknown = room_id!("!unknown:localhost");
-    for command in [
-        RoomCommand::Leave(unknown.to_owned()),
-        RoomCommand::Forget(unknown.to_owned()),
-        RoomCommand::AcceptInvite(unknown.to_owned()),
-        RoomCommand::RejectInvite(unknown.to_owned()),
-    ] {
-        let id = handle.send(Command::Room(command)).await.unwrap();
-        receive_room_failure(&mut events, id, CommandErrorKind::RoomUnknown).await;
-    }
-    stop_engine(handle, &mut events, running).await;
+
+    assert_eq!(
+        handle
+            .leave_room(unknown.to_owned())
+            .await
+            .unwrap_err()
+            .kind,
+        ErrorKind::RoomUnknown
+    );
+    assert_eq!(
+        handle
+            .forget_room(unknown.to_owned())
+            .await
+            .unwrap_err()
+            .kind,
+        ErrorKind::RoomUnknown
+    );
+    assert_eq!(
+        handle
+            .accept_invite(unknown.to_owned())
+            .await
+            .unwrap_err()
+            .kind,
+        ErrorKind::RoomUnknown
+    );
+    assert_eq!(
+        handle
+            .reject_invite(unknown.to_owned())
+            .await
+            .unwrap_err()
+            .kind,
+        ErrorKind::RoomUnknown
+    );
+
+    support::shut_down(&handle, &mut events, running).await;
     drop(server);
 }
 
@@ -235,12 +254,14 @@ async fn account_data_reads_synced_values_and_writes_raw_content() {
         room.deserialize_as::<serde_json::Value>().unwrap()["content"]["event_id"],
         "$seen:localhost"
     );
-    assert!(matches!(
+    assert_eq!(
         handle
             .room_account_data(room_id!("!missing:localhost"), room_type.clone())
-            .await,
-        Err(ClientQueryError::RoomUnknown(_))
-    ));
+            .await
+            .unwrap_err()
+            .kind,
+        ErrorKind::RoomUnknown
+    );
 
     Mock::given(method("PUT"))
         .and(path(
@@ -268,7 +289,7 @@ async fn account_data_reads_synced_values_and_writes_raw_content() {
         .unwrap();
     handle
         .set_room_account_data(
-            room_id,
+            room_id.to_owned(),
             room_type,
             Raw::new(&json!({ "event_id": "$later:localhost" }))
                 .unwrap()
@@ -276,19 +297,21 @@ async fn account_data_reads_synced_values_and_writes_raw_content() {
         )
         .await
         .unwrap();
-    assert!(matches!(
+    assert_eq!(
         handle
             .set_room_account_data(
-                room_id!("!missing:localhost"),
+                room_id!("!missing:localhost").to_owned(),
                 RoomAccountDataEventType::FullyRead,
                 Raw::new(&json!({ "event_id": "$later:localhost" }))
                     .unwrap()
                     .cast_unchecked()
             )
-            .await,
-        Err(ClientQueryError::RoomUnknown(_))
-    ));
-    stop_engine(handle, &mut events, running).await;
+            .await
+            .unwrap_err()
+            .kind,
+        ErrorKind::RoomUnknown
+    );
+    support::shut_down(&handle, &mut events, running).await;
 }
 
 async fn configured_client() -> (MatrixMockServer, matrix_sdk::Client) {
@@ -326,76 +349,3 @@ async fn run_client(
     let running = tokio::spawn(engine.run());
     (handle, events, running)
 }
-
-async fn receive_room_success(events: &mut EventStream, expected_id: CommandId) {
-    tokio::time::timeout(Duration::from_secs(3), async {
-        loop {
-            match events.recv().await.expect("event stream closed") {
-                Event::CommandSucceeded {
-                    id,
-                    command: CommandKind::Room,
-                } if id == expected_id => break,
-                Event::CommandFailed(failure) if failure.id == expected_id => {
-                    panic!("room command failed {failure:?}")
-                }
-                _ => {}
-            }
-        }
-    })
-    .await
-    .expect("room command did not complete");
-}
-
-async fn receive_room_failure(
-    events: &mut EventStream,
-    expected_id: CommandId,
-    expected_kind: CommandErrorKind,
-) {
-    tokio::time::timeout(Duration::from_secs(3), async {
-        loop {
-            match events.recv().await.expect("event stream closed") {
-                Event::CommandFailed(failure) if failure.id == expected_id => {
-                    assert_eq!(failure.command, CommandKind::Room);
-                    assert_eq!(failure.kind, expected_kind);
-                    break;
-                }
-                Event::CommandSucceeded { id, .. } if id == expected_id => {
-                    panic!("room command unexpectedly succeeded")
-                }
-                _ => {}
-            }
-        }
-    })
-    .await
-    .expect("room command did not fail");
-}
-
-async fn stop_engine(
-    handle: ClientHandle,
-    events: &mut EventStream,
-    running: JoinHandle<Result<(), EngineError>>,
-) {
-    let id = handle
-        .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-        .await
-        .unwrap();
-    tokio::time::timeout(Duration::from_secs(3), async {
-        let mut succeeded = false;
-        while let Some(event) = events.recv().await {
-            match event {
-                Event::CommandSucceeded {
-                    id: completed,
-                    command: CommandKind::Lifecycle,
-                } if completed == id => succeeded = true,
-                Event::Stopped => {
-                    assert!(succeeded);
-                    break;
-                }
-                _ => {}
-            }
-        }
-    })
-    .await
-    .expect("engine did not stop");
-    running.await.unwrap().unwrap();
-}

show truncated diff

macltok

Commit 31ce2453c82f

Commit `31ce2453c82f`