macltok

public

Star0

Fork 0

Watch0

56 commits 3 branches 0 tags 0 releases3.0 MiB

Commit `cbb715e11963`

tarball

atagen <boss@atagen.co>2026-10-25 02:35 UTC

32 files changed+6595-193

mentions: persist an encrypted account inbox

Timeline observers cannot fence Sliding Sync checkpoints or retain encrypted candidates until keys arrive. ResponseCommitHook lets the inbox commit before the SDK advances its position, while coverage records the limits of notification history.

Modified file: Cargo.lock+12 additions−10 deletions@@ -1839,6 +1839,7 @@ dependencies = [
  "mime",
  "reqwest",
  "ruma",
+ "rusqlite",
  "serde",
  "serde_json",
  "sha2",
@@ -1849,6 +1850,7 @@ dependencies = [
  "uuid",
  "wasm-bindgen",
  "wasm-bindgen-futures",
+ "wasm-bindgen-test",
  "web-sys",
  "wiremock",
 ]
@@ -2000,7 +2002,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "anymap2",
  "aquamarine",
@@ -2063,7 +2065,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-base"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "as_variant",
  "assert_matches",
@@ -2093,7 +2095,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-common"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "eyeball-im",
  "futures-core",
@@ -2116,7 +2118,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-crypto"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "aes",
  "aquamarine",
@@ -2157,7 +2159,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-indexeddb"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "async-trait",
  "base64",
@@ -2189,7 +2191,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-sqlite"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "as_variant",
  "async-trait",
@@ -2216,7 +2218,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-store-encryption"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "base64",
  "blake3",
@@ -2237,7 +2239,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-test"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "as_variant",
  "ctor",
@@ -2260,7 +2262,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-test-macros"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "quote",
  "syn 2.0.119",
@@ -2269,7 +2271,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-ui"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "as_variant",
  "async-rx",

Modified file: Cargo.toml+16 additions−11 deletions@@ -8,7 +8,7 @@ description = "A compact application backend on top of the Matrix Rust SDK"
 default = []
 mirror = []
 serde = ["dep:serde", "imbl/serde"]
-sqlite = ["matrix-sdk/sqlite", "serde", "dep:url", "dep:matrix-sdk-store-encryption"]
+sqlite = ["matrix-sdk/sqlite", "serde", "dep:url", "dep:matrix-sdk-store-encryption", "dep:rusqlite"]
 bundled-sqlite = ["sqlite", "matrix-sdk/bundled-sqlite"]
 indexeddb = [
     "matrix-sdk/indexeddb",
@@ -26,11 +26,11 @@ indexeddb = [
 futures-util = { version = "0.3.31", default-features = false, features = ["std"] }
 http = "1"
 imbl = { version = "6.1.0", default-features = false }
-matrix-sdk = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "cc2b13ea185c0f694523a3a48d8aadfe366dd767", default-features = false, features = ["e2e-encryption"] }
-matrix-sdk-base = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "cc2b13ea185c0f694523a3a48d8aadfe366dd767", default-features = false }
-matrix-sdk-crypto = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "cc2b13ea185c0f694523a3a48d8aadfe366dd767", default-features = false }
-matrix-sdk-store-encryption = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "cc2b13ea185c0f694523a3a48d8aadfe366dd767", optional = true }
-matrix-sdk-ui = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "cc2b13ea185c0f694523a3a48d8aadfe366dd767", default-features = false }
+matrix-sdk = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "7aace883fbe03d4c3c118b55188fe9519ba8ce48", default-features = false, features = ["e2e-encryption"] }
+matrix-sdk-base = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "7aace883fbe03d4c3c118b55188fe9519ba8ce48", default-features = false }
+matrix-sdk-crypto = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "7aace883fbe03d4c3c118b55188fe9519ba8ce48", default-features = false }
+matrix-sdk-store-encryption = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "7aace883fbe03d4c3c118b55188fe9519ba8ce48", optional = true }
+matrix-sdk-ui = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "7aace883fbe03d4c3c118b55188fe9519ba8ce48", default-features = false }
 ruma = { version = "0.16.0", default-features = false, features = ["unstable-msc2545", "unstable-msc4095"] }
 serde = { version = "1.0.219", features = ["derive", "rc"], optional = true }
 serde_json = "1.0.143"
@@ -40,6 +40,7 @@ sha2 = "0.10.9"
 tokio = { version = "1.47.1", features = ["macros", "sync"] }
 tracing = "0.1.41"
 url = { version = "2.5.7", optional = true }
+rusqlite = { version = "0.37", optional = true }
 
 [target.'cfg(target_family = "wasm")'.dependencies]
 getrandom = { version = "0.2", features = ["js"] }
@@ -47,8 +48,8 @@ getrandom3 = { package = "getrandom", version = "0.3", features = ["wasm_js"] }
 getrandom4 = { package = "getrandom", version = "0.4", features = ["wasm_js"] }
 indexed_db_futures = { package = "matrix_indexed_db_futures", version = "0.7.0", optional = true, features = ["typed-arrays"] }
 js-sys = { version = "0.3.105", optional = true }
-matrix-sdk = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "cc2b13ea185c0f694523a3a48d8aadfe366dd767", default-features = false, features = ["js"] }
-matrix-sdk-ui = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "cc2b13ea185c0f694523a3a48d8aadfe366dd767", default-features = false, features = ["js"] }
+matrix-sdk = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "7aace883fbe03d4c3c118b55188fe9519ba8ce48", default-features = false, features = ["js"] }
+matrix-sdk-ui = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "7aace883fbe03d4c3c118b55188fe9519ba8ce48", default-features = false, features = ["js"] }
 # the sdk's own wasm reqwest leaves out stream, which the bounded media download needs
 reqwest = { version = "0.13.1", default-features = false, features = ["stream"] }
 uuid = { version = "1", features = ["js"] }
@@ -62,12 +63,16 @@ web-sys = { version = "0.3.105", optional = true, features = [
     "WorkerGlobalScope",
 ] }
 
-[dev-dependencies]
-matrix-sdk = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "cc2b13ea185c0f694523a3a48d8aadfe366dd767", default-features = false, features = ["testing"] }
-matrix-sdk-test = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "cc2b13ea185c0f694523a3a48d8aadfe366dd767" }
+[target.'cfg(not(target_family = "wasm"))'.dev-dependencies]
+matrix-sdk = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "7aace883fbe03d4c3c118b55188fe9519ba8ce48", default-features = false, features = ["testing"] }
+matrix-sdk-test = { git = "ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk", rev = "7aace883fbe03d4c3c118b55188fe9519ba8ce48" }
 tokio = { version = "1.47.1", features = ["macros", "rt-multi-thread", "signal", "time"] }
 wiremock = "0.6.5"
 
+[target.'cfg(target_family = "wasm")'.dev-dependencies]
+tokio = { version = "1.47.1", features = ["macros", "rt"] }
+wasm-bindgen-test = "0.3"
+
 [[example]]
 name = "headless"
 required-features = ["sqlite"]

Added file: docs/mentions-discovery.md+341 additions@@ -0,0 +1,341 @@
+# Persistent mentions discovery
+
+This records the SDK audit and current persistent mentions implementation.
+Persistent sessions now commit discovery with Sliding Sync responses, retain an
+encrypted inbox, and expose it through `ClientHandle` and the mirror.
+Historical coverage remains incomplete because room-list sync and notification
+history cannot prove that every past mention was observed.
+
+The audited dependency is Matrix Rust SDK 0.18.0 at fork revision
+`cc2b13ea185c0f694523a3a48d8aadfe366dd767`. macltok now pins fork revision
+`7aace883fbe03d4c3c118b55188fe9519ba8ce48`, which adds the response commit
+hook described below. SDK paths below are relative to the audited revision.
+
+## Findings
+
+The SDK can deliver and decrypt events without opening a UI timeline. macltok
+records observed events and recovers candidates through notification history,
+but neither source establishes complete historical coverage.
+
+The SDK audit found that an awaited event handler can hold back the Sliding
+Sync position until a macltok transaction commits, while a background
+broadcast consumer cannot provide that guarantee. Handlers cannot propagate
+commit errors, and response processing outlives cancellation of the calling
+sync task. These limits motivated the fallible response-commit hook now
+implemented in the pinned SDK fork.
+
+## Sync coverage
+
+macltok constructs `SyncService` in `src/engine/mod.rs` and uses the SDK room
+list configuration. The list starts with the selective range `0..=19`. After
+setup it grows by 100 rooms per response, without an SDK-side maximum, until
+it reaches the server's room count. Recovery and sufficiently long idle
+periods can return it to the initial selective range before it grows again.
+The default list timeline limit is one event per room on initial delivery.
+Subsequent changes for covered rooms continue arriving through sync.
+
+Opening a room separately subscribes it with a
+timeline limit of 20. macltok's `update_room_subscriptions` and
+`watchers::room_subscriptions` manage those explicit subscriptions for active
+room actors only. The mentions response hook filters entries to joined rooms.
+The built-in list still includes invited rooms.
+
+Sources are `crates/matrix-sdk-ui/src/room_list_service/mod.rs`,
+`crates/matrix-sdk-ui/src/room_list_service/state.rs`, and
+`crates/matrix-sdk/src/sliding_sync/list/request_generator.rs`.
+
+The default one-event initial window cannot recover all earlier pings, including
+messages sent while the client was offline. Raising
+`SyncServiceBuilder::with_room_list_timeline_limit` increases the initial
+window but does not establish continuous history. The response hook processes
+joined-room events and records limited timelines, initial room coverage,
+checkpoint discontinuities, and recovery gaps.
+
+## Observation and durable commit
+
+`Client::subscribe_to_all_room_updates` returns a bounded broadcast receiver
+of `RoomUpdates`. Its `joined` map includes processed timeline events with raw
+decrypted content when available and optional evaluated push actions. It does
+not require a UI timeline. Lag is an error that requires recovery, not an
+invitation to skip to the next update.
+
+`Client::observe_events` retains only the latest observation and can miss
+intermediate events. It is unsuitable for durable discovery.
+
+An earlier probe registers `Client::add_event_handler` for
+`Raw<AnySyncTimelineEvent>` with `Room` context before sync starts. Its awaited
+handler demonstrates event ordering, but it cannot report commit failures
+reliably and is not the production ingestion path. Production uses the
+fallible Sliding Sync response hook described below.
+
+For Sliding Sync v5, the response processor awaits event handlers before
+updating and persisting `pos`. The response hook commits the inbox first, so
+a crash permits replay without skipping committed candidates. Stable event
+keys make replay idempotent. The hook acknowledgement does not wait for
+context capture, a UI subscriber, or the engine event stream to drain.
+
+For ordinary event handlers, the SDK logs and discards handler errors, so
+returning an error after a failed write still permits `pos` to advance. A
+pending handler alone also does not provide a reliable shutdown path. The SDK
+runs response handling in a detached task that outlives cancellation of
+`sync_once` or its caller. Aborting the engine's sync task cannot prevent a
+suspended handler from later returning and advancing the position. Registering
+a handler and placing work on a queue without awaiting its commit does not
+close the crash window.
+
+macltok uses shared `pos` through its SDK service and commits each response
+batch through one serialized mentions actor before the hook acknowledges it.
+The actor records joined-room events, raw encrypted candidates, limited
+timeline gaps, and the connection checkpoint in the same inbox revision.
+Stable room and event keys make replay idempotent. Context capture, mirror
+publication, and event-stream delivery continue after the commit. The classic
+sync `next_batch` ordering differs and does not establish this guarantee.
+Nor does this ordering make arbitrary concurrent sync loops safe.
+
+Sources are `crates/matrix-sdk/src/event_handler/mod.rs`,
+`crates/matrix-sdk/src/event_handler/static_events.rs`,
+`crates/matrix-sdk/src/sliding_sync/client.rs`,
+`crates/matrix-sdk/src/sliding_sync/mod.rs`, and
+`crates/matrix-sdk/src/sliding_sync/cache.rs`.
+
+### SDK commit hook implementation
+
+The local SDK workspace at `../matrix-rust-sdk-mentions` implements the
+fallible asynchronous response-commit hook through `ResponseCommitHook` and
+`ResponseCommitBatch`. `SyncServiceBuilder` forwards it only to its room-list
+connection, so independent notification lookups are unaffected.
+
+The hook receives the processed room events, original room payloads, limited
+flags, pagination tokens, connection identity, and previous and next position
+identifiers. It runs before response handlers and observers and before `pos`
+is updated or saved. SDK room state may already have been saved. A successful
+acknowledgement follows the macltok inbox transaction. A failed or dropped
+acknowledgement returns a sync error without advancing the position.
+
+The hook runs outside SDK store locks and supports local futures on wasm and
+sendable futures natively. The default absent hook preserves existing SDK
+behavior. Detached response processing observes a dropped store
+acknowledgement after its caller is cancelled. Checkpoint replay works after
+SDK room state was saved, and stable event keys deduplicate repeated commits.
+
+The SDK audit and focused validation covered commit ordering, failed and
+dropped acknowledgements, caller cancellation, replay after room-state
+persistence, restoring a previous checkpoint, absent-hook behavior, builder
+forwarding, and connection isolation. The SDK UI library also received a
+focused wasm compilation check with its `js` feature. The SDK changes are
+published to the user's fork under `mentions-commit-hook`, and the manifest
+and both macltok lockfiles pin revision
+`7aace883fbe03d4c3c118b55188fe9519ba8ce48`.
+
+## Event cache and delayed decryption
+
+`EventCache::subscribe` starts global room-update ingestion. The SDK room list
+service already calls it during construction. Its generic update subscription
+identifies the affected room, then `Room::event_cache` and
+`RoomEventCache::find_event` can retrieve an event. This does not require a
+`matrix-sdk-ui::Timeline` or a retained subscriber per room.
+
+`EventCache::subscribe_to_decryption_reports` reports resolved event IDs,
+lag, and backup availability. `EventCache::request_decryption` accepts room
+and Megolm session IDs for explicit retries. `Room::decrypt_event` is also
+public and can decrypt a retained raw event independently of a UI timeline.
+
+The late-key probe confirms automatic decryption and retrieval of a structured
+mention through the global cache without a UI timeline. Cached push actions
+are optional. Re-evaluate them with `Room::event_push_actions` when needed,
+and treat missing push context as unresolved rather than a negative result.
+The room's own membership state is needed to build that push context.
+
+The cache is not a durable ingestion journal. Its room broadcasts and generic
+updates can lag, and cache retention can remove events. SQLite and IndexedDB
+builders select persistent SDK event-cache stores, while the default
+store-free client uses memory. Even with persistence, the asynchronous cache
+consumer is not awaited before Sliding Sync saves its position.
+
+The inbox retains unresolved encrypted candidates as encrypted raw events
+within a configurable bound. It retries due candidates at startup and resets
+their retry time when decryption reports arrive. Candidate eviction sets the
+coverage truncation flag. Imported keys and backups cannot reconstruct events
+already discarded by every cache.
+
+Sources are `crates/matrix-sdk/src/event_cache/mod.rs`,
+`crates/matrix-sdk/src/event_cache/redecryptor.rs`,
+`crates/matrix-sdk/src/event_cache/caches/room/mod.rs`, and
+`crates/matrix-sdk/src/room/mod.rs`.
+
+## Mention policy
+
+Structured `m.mentions.user_ids` and `m.mentions.room` supply semantic
+candidates. The classifier does not infer pings from rendered bodies or
+unread counts. A reply relationship alone does not prove that a reply notifies
+the user, so reply reasons require notification metadata and confirmation that
+the referenced event belongs to the signed-in user.
+
+`Room::event_push_actions` evaluates push rules but does not independently
+filter ignored senders. The classifier calls `Client::is_user_ignored` and
+rechecks entries when the ignore list changes.
+
+A room mute can suppress evaluated notification actions while structured
+mention metadata remains present. The classifier retains explicit user
+mentions in muted rooms and marks notification delivery as suppressed. Reply
+reasons require both a reply to the user and a notifying highlight. Room-wide
+reasons require the relevant push conditions and sender power level. Missing
+authorization context remains unresolved for reevaluation. Keyword-only
+notifications are outside the inbox. The classifier excludes the signed-in
+user's own events even when they contain explicit mention metadata.
+
+The existing `NotificationClient` combines notification evaluation with
+ignored-sender filtering. Its public lookup takes known room and event IDs.
+It is useful for resolving a candidate, but filtered results erase the
+distinction between mute policy and an absent semantic mention. It is not the
+sole classifier for this inbox.
+
+## Historical candidates and gaps
+
+Ruma exposes
+`api::client::push::get_notifications::v3::Request`, sent with `Client::send`.
+It accepts opaque `from`, optional `limit`, and optional `only` fields.
+Responses contain notifications and an optional `next_token`. macltok requests
+50 notifications per page. Entries include raw events, room IDs, timestamps,
+actions, and server notification read state, which does not initialize or
+replace local inbox read state.
+
+The service uses this endpoint as a bounded candidate source, validates
+events after decryption, and applies the live mention policy. Each page's
+observed candidates and cursor are committed together in the encrypted inbox,
+including unresolved encrypted candidates. A failed commit leaves the prior
+cursor available for replay.
+
+An exhausted notification list does not mean complete room history. Muted-room
+pings, encrypted mentions not recognized by the server, expired notifications,
+and server-specific retention can be absent. Recovery inspects at most 20 pages
+of 50 notifications per run and resumes from committed cursors later. The
+older-history cursor is separate from the cursor for scans from the newest
+notifications. A newest scan records an anchor and runs at startup and every
+60 seconds. It follows the committed cursor until it reaches that anchor,
+resuming on later runs when needed to find newly added notifications.
+
+SDK cache gaps retain pagination tokens and support room pagination, but
+running that pagination mutates the live cache. Mention context capture uses
+independent `/context` and `/messages` requests. Tokens may expire. Context can
+be retried around a known event while the room remains joined, and known gaps
+remain visible when continuity cannot be established.
+
+Coverage exposes the earliest observed timestamp, history-endpoint support,
+recovery activity, known room gaps, unresolved candidate count, and retention
+truncation. The earliest timestamp is a summary, not proof that every room is
+covered after that time. The inbox keeps its incomplete-history flag even
+after notification pagination ends.
+
+Complete offline mention recovery across arbitrary muted and encrypted rooms
+is not supplied by this endpoint or by the current sync configuration. It
+would require a retained, replayable event source or bounded per-room history
+recovery with proof of continuity. The notification endpoint does not provide
+that guarantee.
+
+## Storage, context, and API
+
+`src/mentions/store` implements encrypted SQLite and IndexedDB record stores.
+Persistent session construction opens the account store, and local logout
+deletes it alongside the SDK stores. The mentions actor owns the store for
+inbox commits and discovery checkpoints.
+
+The passphrase wraps a random SDK `StoreCipher`. Logical keys are hashed, and
+authenticated encrypted records include schema, account identity, and logical
+key. Restore rejects mismatched accounts, unsupported schemas, corrupt records,
+and inconsistent record counts or byte totals. Atomic transactions compare the
+previous encrypted header before publishing a new revision, so stale writers
+cannot overwrite a newer checkpoint.
+
+The default budget is 64 MiB of encrypted records, hashed keys, header, and
+wrapped cipher, excluding database page overhead. The store record cap is
+35,128. The inbox defaults to 5,000 entries, 25,000 shared context events, and
+5,000 unresolved candidates within that byte budget. When a size or record
+limit requires eviction, the store drops bounded data and marks coverage
+truncated.
+
+The storage tests cover atomic restore of records and checkpoints, stale
+writers, capacity failure, encrypted physical records, wrong credentials or
+account, corruption, unsupported schemas, and injected SQLite write failure.
+The inbox tests cover batch failure, notification recovery, live context
+updates, and capture persistence across session resume.
+
+
+The inbox is serialized into one `inbox` value and encrypted as a single
+record on every revision. Each update reserializes and re-encrypts the retained
+inbox, so write cost scales with retained data. Decrypted previews, saved
+context, raw candidates, pending capture state, media source registrations,
+read state, coverage, and sync checkpoints stay inside the authenticated
+encrypted payload. SDK SQLite custom values remain plaintext and are not used
+for decrypted mentions.
+
+Context capture in `src/engine/context.rs` sizes the before and after requests
+independently and retains the media registrations produced by normalization.
+Each capture requests up to 10 events on each side. At most two capture jobs
+run concurrently, with up to 128 pending or failed entries considered for
+scheduling at a time. Capture uses independent `/context` and `/messages`
+requests, so it does not paginate the live cache. Media source registrations
+are encrypted with saved events and registered again when context is read.
+Media bodies and key material do not enter the mentions public model.
+
+One account-scoped mentions actor serializes store commits for entries,
+unresolved candidates, shared context events, read state, revisions, discovery
+checkpoints, and retention decisions.
+
+Pending capture state is durable with the inbox, so interrupted capture can
+resume after startup. When a room leaves the joined state, saved context
+remains readable and its capture state becomes unavailable. Refetch is
+disabled after departure.
+
+Store publication follows commit. `ClientHandle` exposes page, context, retry,
+read, read-through, and recovery methods. The public `Command`, mention models,
+mirror state, and updates support serde when the `serde` feature is enabled,
+so native and browser consumers can transport them. Browser worker integration
+is a consumer phase after SDK and macltok revision publication. Malice's worker
+still needs mention variants in its explicit `Request` dispatch and TypeScript
+methods.
+
+Mirror snapshots contain at most 50 entry previews, coverage, unread count,
+and a committed revision boundary, with no saved context bodies. The watcher
+coalesces updates and computes upserts and removals relative to the previous
+bounded snapshot it observed. A missed update therefore leaves the latest
+snapshot authoritative. A removal can mean an entry fell out of the top 50,
+and does not imply that it was deleted from the inbox. Pagination uses
+timestamp and stable event key within a discovery revision boundary.
+Read-through boundaries exclude mentions first discovered or reactivated after
+that boundary, including older messages resolved by late decryption.
+
+## Executable probes
+
+`tests/mentions_discovery.rs` exercises unopened-room update and cache access,
+push-rule behavior for ignored senders and muted rooms, and typed
+notification-history pagination.
+
+`tests/mentions_decryption.rs` exchanges a real encrypted event and a delayed
+room key between two mock clients, then retrieves the decrypted mention
+without opening a UI timeline.
+
+`tests/mentions_checkpoint.rs` holds an event handler pending and verifies
+that the SDK has not persisted its position. It cancels the calling task,
+then acknowledges the handler and verifies that detached response processing
+still saves the position. A new Sliding Sync instance restores that position.
+This is the historical event-handler ordering probe. It does not exercise the
+production response-commit hook or the durable inbox transaction. It also
+demonstrates that returning a handler error still advances the position.
+
+`tests/mentions_inbox.rs` covers live mention classification, read-through
+with revision boundaries, independent context limits, and persistence across
+session resume. `tests/mentions_late_decryption.rs` verifies that a delayed room key
+updates the production inbox once. `src/mentions/service_tests.rs` covers
+checkpoint rollback, notification-history recovery, and context updates.
+`src/mentions/store/tests.rs` exercises encrypted record restore, capacity,
+stale writers, and corruption handling.
+
+These probes establish SDK behavior against mocked responses. They do not
+establish homeserver notification retention, room-list completeness, or
+complete history on a deployed server.
+
+Focused validation passed 63 native tests and 12 shared inbox and IndexedDB
+tests in headless Firefox. Compilation checks also pass without storage
+features and for wasm with IndexedDB and mirror support. The full flake gate
+was skipped by request.

Modified file: harness/web/Cargo.lock+9 additions−8 deletions@@ -1733,6 +1733,7 @@ dependencies = [
  "reqwest",
  "ruma",
  "serde",
+ "serde_json",
  "sha2",
  "thiserror 2.0.20",
  "tokio",
@@ -1906,7 +1907,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "anymap2",
  "aquamarine",
@@ -1966,7 +1967,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-base"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "as_variant",
  "async-trait",
@@ -1992,7 +1993,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-common"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "eyeball-im",
  "futures-core",
@@ -2015,7 +2016,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-crypto"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "aes",
  "aquamarine",
@@ -2055,7 +2056,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-indexeddb"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "async-trait",
  "base64",
@@ -2087,7 +2088,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-sqlite"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "as_variant",
  "async-trait",
@@ -2114,7 +2115,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-store-encryption"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "base64",
  "blake3",
@@ -2135,7 +2136,7 @@ dependencies = [
 [[package]]
 name = "matrix-sdk-ui"
 version = "0.18.0"
-source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=cc2b13ea185c0f694523a3a48d8aadfe366dd767#cc2b13ea185c0f694523a3a48d8aadfe366dd767"
+source = "git+ssh://brewery@pls.lobotomise.me:33/atagen/matrix-rust-sdk?rev=7aace883fbe03d4c3c118b55188fe9519ba8ce48#7aace883fbe03d4c3c118b55188fe9519ba8ce48"
 dependencies = [
  "as_variant",
  "async-rx",

Modified file: src/account.rs+29 additions@@ -42,6 +42,7 @@ pub struct Session {
 
 /// taken as soon as the client exists, since the sdk can refresh before there's an engine
 struct Tracking {
+    store: Arc<dyn SessionStore>,
     session_changes: broadcast::Receiver<SessionChange>,
     persistence: Option<Persistence>,
     #[cfg(not(target_family = "wasm"))]
@@ -312,6 +313,17 @@ impl StoreConfig {
         &self.passphrase
     }
 
+    #[cfg(feature = "sqlite")]
+    pub(crate) fn mentions_location(&self) -> PathBuf {
+        let StoreLocation::Sqlite(path) = &self.location;
+        path.join("macltok-mentions.sqlite3")
+    }
+
+    #[cfg(feature = "indexeddb")]
+    pub(crate) fn mentions_location(&self) -> String {
+        format!("{}::macltok-mentions", self.indexeddb_name())
+    }
+
     #[cfg(feature = "indexeddb")]
     pub(crate) fn indexeddb_name(&self) -> &str {
         let StoreLocation::IndexedDb(name) = &self.location;
@@ -834,12 +846,28 @@ impl Session {
         self,
         config: EngineConfig,
     ) -> Result<(Engine, ClientHandle, EventStream), AccountError> {
+        let account = crate::mentions::store::Account {
+            homeserver: self.client.homeserver().to_string(),
+            user_id: self
+                .client
+                .user_id()
+                .ok_or(AccountError::MissingSession)?
+                .to_owned(),
+        };
+        let mentions = crate::mentions::store::MentionsStore::open(
+            self.tracking.store.store(),
+            account,
+            config.max_mentions_bytes,
+        )
+        .await
+        .map_err(|error| account_error("opening the mentions store", error))?;
         Engine::with_persistence(
             self.client,
             config,
             self.tracking.session_changes,
             self.tracking.persistence,
             Some(self.store_lock),
+            Some(mentions),
         )
         .await
         .map_err(AccountError::from)
@@ -872,6 +900,7 @@ impl Tracking {
         #[cfg(not(target_family = "wasm"))]
         let inline = save_inline(client, sessions.clone(), results)?;
         Ok(Self {
+            store: sessions.clone(),
             session_changes,
             persistence: Some(Persistence {
                 save: Box::new(move |client| {

Modified file: src/engine/context.rs+164 additions−131 deletions@@ -1,20 +1,23 @@
 use std::sync::Arc;
 
-use matrix_sdk::{room::MessagesOptions, Room};
-use matrix_sdk_ui::timeline::{RoomExt, TimelineEventFocusThreadMode, TimelineFocus};
-use ruma::{uint, OwnedEventId};
+use matrix_sdk::{
+    Room, deserialized_responses::TimelineEvent as SdkTimelineEvent, room::MessagesOptions,
+};
+use ruma::{OwnedEventId, OwnedUserId, RoomId, UInt};
 
 use crate::{
-    normalise::{normalise_timeline, MediaScope},
     Error, ErrorKind, EventContext, EventContextCommand, EventContextDirection, EventContextPage,
     TimelineItem,
+    engine::MediaService,
+    normalise::{MediaRegistration, normalise_observed},
 };
 
 const MAX_CONTEXT_LIMIT: u16 = 50;
 
 pub(crate) async fn execute(
     room: Room,
-    current_user_id: Option<ruma::OwnedUserId>,
+    current_user_id: Option<OwnedUserId>,
+    media: Arc<MediaService>,
     command: EventContextCommand,
 ) -> Result<crate::CommandOutput, Error> {
     if let EventContextCommand::Before { token, limit, .. }
@@ -30,6 +33,7 @@ pub(crate) async fn execute(
         return execute_page(
             room,
             current_user_id,
+            media,
             token,
             *limit,
             matches!(command, EventContextCommand::Before { .. }),
@@ -37,7 +41,7 @@ pub(crate) async fn execute(
         .await;
     }
 
-    let (event_id, limit) = match &command {
+    let (event_id, before_limit, after_limit) = match &command {
         EventContextCommand::Fetch {
             event_id,
             before_limit,
@@ -46,71 +50,139 @@ pub(crate) async fn execute(
         } => {
             validate_limit(*before_limit)?;
             validate_limit(*after_limit)?;
-            (event_id.clone(), (*before_limit).max(*after_limit))
+            (event_id.clone(), *before_limit, *after_limit)
         }
         EventContextCommand::Before { .. } | EventContextCommand::After { .. } => unreachable!(),
     };
-    validate_limit(limit)?;
-
-    let raw_context = if matches!(command, EventContextCommand::Fetch { .. }) {
-        Some(
-            room.event_with_context(&event_id, false, uint!(0), None)
-                .await
-                .map_err(|source| {
-                    let error = Error::from_sdk("fetching event context failed", source);
-                    if error
-                        .server
-                        .as_ref()
-                        .is_some_and(|server| server.status == 404)
-                    {
-                        Error::new(ErrorKind::EventNotFound, "event was not found")
-                    } else {
-                        error
-                    }
-                })?,
-        )
-    } else {
-        None
-    };
+    let (context, registrations, _) =
+        capture(room, current_user_id, event_id, before_limit, after_limit).await?;
+    media.register(registrations).await;
+    Ok(crate::CommandOutput::EventContext(context))
+}
 
-    let focus = TimelineFocus::Event {
-        target: event_id.clone(),
-        num_context_events: limit,
-        thread_mode: TimelineEventFocusThreadMode::Automatic {
-            hide_threaded_events: true,
-        },
-    };
-    let timeline = room
-        .timeline_builder()
-        .with_focus(focus)
-        .build()
+pub(crate) async fn capture(
+    room: Room,
+    current_user_id: Option<OwnedUserId>,
+    event_id: OwnedEventId,
+    before_limit: u16,
+    after_limit: u16,
+) -> Result<(EventContext, Vec<MediaRegistration>, Vec<serde_json::Value>), Error> {
+    validate_limit(before_limit)?;
+    validate_limit(after_limit)?;
+    let raw = room
+        .event_with_context(&event_id, false, UInt::from(0_u16), None)
         .await
         .map_err(|source| {
-            Error::with_source(ErrorKind::Timeline, "building event context failed", source)
+            let error = Error::from_sdk("fetching event context failed", source);
+            if error
+                .server
+                .as_ref()
+                .is_some_and(|server| server.status == 404)
+            {
+                Error::new(ErrorKind::EventNotFound, "event was not found")
+            } else {
+                error
+            }
         })?;
-
-    if let EventContextCommand::Fetch { .. } = command {
-        let raw = raw_context.expect("fetch context response");
-        let normalized = normalize_items(timeline.items().await, current_user_id.as_deref());
-        let (before, event, after) = split_items(normalized, &event_id);
-        if event.is_none() && raw.event.is_none() {
-            return Err(Error::new(ErrorKind::EventNotFound, "event was not found"));
-        }
-        return Ok(crate::CommandOutput::EventContext(EventContext {
-            events_before: before,
-            event,
-            events_after: after,
-            start_token: raw.prev_batch_token,
-            end_token: raw.next_batch_token,
-        }));
+    if raw.event.is_none() {
+        return Err(Error::new(ErrorKind::EventNotFound, "event was not found"));
     }
+    let before = fetch_side(
+        &room,
+        raw.prev_batch_token.as_deref(),
+        before_limit,
+        true,
+        current_user_id.as_deref(),
+    );
+    let after = fetch_side(
+        &room,
+        raw.next_batch_token.as_deref(),
+        after_limit,
+        false,
+        current_user_id.as_deref(),
+    );
+    let (events_before, mut before_media, start_token, mut observed) = before.await?;
+    let (events_after, after_media, end_token, following) = after.await?;
+    observed.extend(following);
+    if let Some(value) = raw
+        .event
+        .as_ref()
+        .and_then(|event| serde_json::from_str(event.raw().json().get()).ok())
+    {
+        observed.push(value);
+    }
+    let event = raw.event.as_ref().and_then(|event| {
+        normalise_sdk_event(event, current_user_id.as_deref(), room.room_id()).map(
+            |(item, media)| {
+                before_media.extend(media);
+                item
+            },
+        )
+    });
+    before_media.extend(after_media);
+    Ok((
+        EventContext {
+            events_before,
+            event,
+            events_after,
+            start_token,
+            end_token,
+        },
+        before_media,
+        observed,
+    ))
+}
 
-    unreachable!("fetch context returned above")
+async fn fetch_side(
+    room: &Room,
+    token: Option<&str>,
+    limit: u16,
+    backwards: bool,
+    current_user_id: Option<&ruma::UserId>,
+) -> Result<
+    (
+        Vec<TimelineItem>,
+        Vec<MediaRegistration>,
+        Option<String>,
+        Vec<serde_json::Value>,
+    ),
+    Error,
+> {
+    if limit == 0 {
+        return Ok((Vec::new(), Vec::new(), token.map(str::to_owned), Vec::new()));
+    }
+    let Some(token) = token else {
+        return Ok((Vec::new(), Vec::new(), None, Vec::new()));
+    };
+    let mut options = if backwards {
+        MessagesOptions::backward()
+    } else {
+        MessagesOptions::forward()
+    };
+    options = options.from(token);
+    options.limit = UInt::from(limit);
+    let messages = room
+        .messages(options)
+        .await
+        .map_err(|source| Error::from_sdk("fetching event context events failed", source))?;
+    let mut events = messages.chunk;
+    events.truncate(usize::from(limit));
+    if backwards {
+        events.reverse();
+    }
+    let next_token = messages.end;
+    let observed = events
+        .iter()
+        .filter_map(|event| serde_json::from_str(event.raw().json().get()).ok())
+        .collect();
+    let (items, media) = normalise_events(events, current_user_id, room.room_id());
+    Ok((items, media, next_token, observed))
 }
 
 async fn execute_page(
     room: Room,
-    current_user_id: Option<ruma::OwnedUserId>,
+    current_user_id: Option<OwnedUserId>,
+    media: Arc<MediaService>,
     token: &str,
     limit: u16,
     backwards: bool,
@@ -121,55 +193,20 @@ async fn execute_page(
         MessagesOptions::forward()
     };
     options = options.from(token);
-    options.limit = ruma::UInt::from(limit);
+    options.limit = UInt::from(limit);
     let messages = room
         .messages(options)
         .await
         .map_err(|source| Error::from_sdk("fetching event context page failed", source))?;
-
-    let ids: Vec<_> = messages
-        .chunk
-        .iter()
-        .filter_map(|event| event.event_id())
-        .collect();
-    let normalized = if let Some(target) = ids.first() {
-        let focus = TimelineFocus::Event {
-            target: target.clone(),
-            num_context_events: limit,
-            thread_mode: TimelineEventFocusThreadMode::Automatic {
-                hide_threaded_events: false,
-            },
-        };
-        let timeline = room
-            .timeline_builder()
-            .with_focus(focus)
-            .build()
-            .await
-            .map_err(|source| {
-                Error::with_source(
-                    ErrorKind::Timeline,
-                    "building event context page failed",
-                    source,
-                )
-            })?;
-        normalize_items(timeline.items().await, current_user_id.as_deref())
-    } else {
-        Vec::new()
-    };
-
-    let mut by_id = std::collections::HashMap::new();
-    for item in normalized {
-        if let TimelineItem::Event(event) = &item {
-            if let Some(event_id) = &event.event_id {
-                by_id.insert(event_id.clone(), item);
-            }
-        }
-    }
-    let mut events: Vec<_> = ids.iter().filter_map(|id| by_id.remove(id)).collect();
+    let next_token = messages.end.clone();
+    let mut events = messages.chunk;
+    events.truncate(usize::from(limit));
     if backwards {
         events.reverse();
     }
-    let next_token = messages.end.clone();
+    let (events, registrations) =
+        normalise_events(events, current_user_id.as_deref(), room.room_id());
+    media.register(registrations).await;
     let end_reached = next_token.is_none();
     let direction = if backwards {
         EventContextDirection::Before
@@ -184,41 +221,37 @@ async fn execute_page(
     }))
 }
 
-fn validate_limit(limit: u16) -> Result<(), Error> {
-    if limit > MAX_CONTEXT_LIMIT {
-        Err(Error::new(ErrorKind::Invalid, "context limit exceeds 50"))
-    } else {
-        Ok(())
+fn normalise_events(
+    events: Vec<SdkTimelineEvent>,
+    current_user_id: Option<&ruma::UserId>,
+    room_id: &RoomId,
+) -> (Vec<TimelineItem>, Vec<MediaRegistration>) {
+    let mut items = Vec::with_capacity(events.len());
+    let mut media = Vec::new();
+    for event in events {
+        if let Some((item, registrations)) = normalise_sdk_event(&event, current_user_id, room_id) {
+            items.push(item);
+            media.extend(registrations);
+        }
     }
+    (items, media)
 }
 
-fn normalize_items(
-    items: imbl::Vector<Arc<matrix_sdk_ui::timeline::TimelineItem>>,
+fn normalise_sdk_event(
+    event: &SdkTimelineEvent,
     current_user_id: Option<&ruma::UserId>,
-) -> Vec<TimelineItem> {
-    let scope = MediaScope::new();
-    normalise_timeline(items.iter(), current_user_id, &scope)
-        .items
-        .into_iter()
-        .collect()
+    room_id: &RoomId,
+) -> Option<(TimelineItem, Vec<MediaRegistration>)> {
+    let value: serde_json::Value = serde_json::from_str(event.raw().json().get()).ok()?;
+    let event_id = value.get("event_id")?.as_str()?;
+    let identity = format!("{room_id}\n{event_id}");
+    normalise_observed(&value, current_user_id, &identity)
 }
 
-fn split_items(
-    items: Vec<TimelineItem>,
-    event_id: &OwnedEventId,
-) -> (Vec<TimelineItem>, Option<TimelineItem>, Vec<TimelineItem>) {
-    let items: Vec<_> = items
-        .into_iter()
-        .filter(|item| matches!(item, TimelineItem::Event(_)))
-        .collect();
-    let target = items.iter().position(|item| {
-        matches!(item, TimelineItem::Event(event) if event.event_id.as_ref() == Some(event_id))
-    });
-    let Some(index) = target else {
-        return (items, None, Vec::new());
-    };
-    let mut before = items;
-    let after = before.split_off(index + 1);
-    let event = before.pop();
-    (before, event, after)
+fn validate_limit(limit: u16) -> Result<(), Error> {
+    if limit > MAX_CONTEXT_LIMIT {
+        Err(Error::new(ErrorKind::Invalid, "context limit exceeds 50"))
+    } else {
+        Ok(())
+    }
 }

Modified file: src/engine/mod.rs+99 additions−16 deletions@@ -1,5 +1,5 @@
 mod commands;
-mod context;
+pub(crate) mod context;
 pub(crate) mod executor;
 mod media;
 mod mutations;
@@ -33,6 +33,11 @@ pub(crate) use crate::store_lock::StoreLock;
 #[cfg(not(any(feature = "sqlite", feature = "indexeddb")))]
 pub(crate) enum StoreLock {}
 
+#[cfg(any(feature = "sqlite", feature = "indexeddb"))]
+pub(crate) use crate::mentions::store::MentionsStore;
+#[cfg(not(any(feature = "sqlite", feature = "indexeddb")))]
+pub(crate) enum MentionsStore {}
+
 use self::{
     commands::Job,
     executor::{EngineBoxFuture, TaskSet},
@@ -58,12 +63,40 @@ pub struct EngineConfig {
     pub initial_history_limit: u16,
     pub max_media_bytes: usize,
     pub max_media_sources: usize,
+    pub max_mentions_bytes: usize,
+    pub max_mentions_entries: usize,
+    pub max_mention_context_events: usize,
+    pub max_mention_candidates: usize,
     /// warm a room up for sending when it's opened or someone starts typing in it
     pub prepare_to_send: bool,
 }
 
 impl EngineConfig {
     #[must_use]
+    pub const fn with_max_mentions_bytes(mut self, bytes: usize) -> Self {
+        self.max_mentions_bytes = bytes;
+        self
+    }
+
+    #[must_use]
+    pub const fn with_max_mentions_entries(mut self, entries: usize) -> Self {
+        self.max_mentions_entries = entries;
+        self
+    }
+
+    #[must_use]
+    pub const fn with_max_mention_context_events(mut self, events: usize) -> Self {
+        self.max_mention_context_events = events;
+        self
+    }
+
+    #[must_use]
+    pub const fn with_max_mention_candidates(mut self, candidates: usize) -> Self {
+        self.max_mention_candidates = candidates;
+        self
+    }
+
+    #[must_use]
     pub const fn with_command_capacity(mut self, capacity: usize) -> Self {
         self.command_capacity = capacity;
         self
@@ -108,6 +141,10 @@ impl Default for EngineConfig {
             initial_history_limit: 30,
             max_media_bytes: 20 * 1024 * 1024,
             max_media_sources: 2_048,
+            max_mentions_bytes: 64 * 1024 * 1024,
+            max_mentions_entries: 5_000,
+            max_mention_context_events: 25_000,
+            max_mention_candidates: 5_000,
             prepare_to_send: true,
         }
     }
@@ -117,10 +154,12 @@ impl Default for EngineConfig {
 pub enum EngineError {
     #[error("the Matrix client is not authenticated")]
     Unauthenticated,
-    #[error("command, event, and media source capacities must be nonzero")]
+    #[error("command, event, media source, and mentions capacities must be nonzero")]
     ZeroCapacity,
     #[error("could not build the sync service")]
     SyncService(#[source] matrix_sdk_ui::sync_service::Error),
+    #[error("could not open the mentions service")]
+    MentionsStore(#[source] crate::Error),
     #[error("the event receiver has closed")]
     EventReceiverClosed,
     #[error("engine task {task} panicked")]
@@ -133,9 +172,10 @@ impl EngineError {
             kind: match self {
                 Self::EventReceiverClosed => EngineErrorKind::EventReceiverClosed,
                 Self::TaskPanicked { .. } => EngineErrorKind::Watcher,
-                Self::Unauthenticated | Self::ZeroCapacity | Self::SyncService(_) => {
-                    EngineErrorKind::Other
-                }
+                Self::Unauthenticated
+                | Self::ZeroCapacity
+                | Self::SyncService(_)
+                | Self::MentionsStore(_) => EngineErrorKind::Other,
             },
             message: self.to_string(),
         }
@@ -282,6 +322,9 @@ pub struct Engine {
     preparations: prepare::Preparations,
     /// shared with every `ClientHandle`, so the store stays locked while the client is reachable
     _store_lock: Option<Arc<StoreLock>>,
+    mentions: crate::mentions::service::Handle,
+    mentions_service: Option<crate::mentions::service::Service>,
+    mentions_updates: Option<watch::Receiver<crate::MentionsPage>>,
 }
 
 impl Engine {
@@ -291,7 +334,7 @@ impl Engine {
         config: EngineConfig,
     ) -> Result<(Self, ClientHandle, EventStream), EngineError> {
         let session_changes = client.subscribe_to_session_changes();
-        Self::with_persistence(client, config, session_changes, None, None).await
+        Self::with_persistence(client, config, session_changes, None, None, None).await
     }
 
     /// `session_changes` is taken when the client is built, since the sdk can refresh
@@ -302,6 +345,7 @@ impl Engine {
         session_changes: broadcast::Receiver<SessionChange>,
         persistence: Option<Persistence>,
         store_lock: Option<StoreLock>,
+        mentions: Option<MentionsStore>,
     ) -> Result<(Self, ClientHandle, EventStream), EngineError> {
         if client.user_id().is_none() {
             return Err(EngineError::Unauthenticated);
@@ -309,9 +353,27 @@ impl Engine {
         if config.command_capacity == 0
             || config.event_capacity == 0
             || config.max_media_sources == 0
+            || config.max_mentions_entries == 0
+            || config.max_mention_context_events == 0
+            || config.max_mention_candidates == 0
         {
             return Err(EngineError::ZeroCapacity);
         }
+        let store_lock = store_lock.map(Arc::new);
+        let media = Arc::new(MediaService::new(
+            client.clone(),
+            config.max_media_bytes,
+            config.max_media_sources,
+        ));
+        let (mentions, mentions_service, mentions_updates) =
+            crate::mentions::service::Service::new(
+                client.clone(),
+                media.clone(),
+                mentions,
+                config.clone(),
+            )
+            .await
+            .map_err(EngineError::MentionsStore)?;
         let sync = Arc::new(
             SyncService::builder(client.clone())
                 .with_offline_mode()
@@ -319,16 +381,11 @@ impl Engine {
                     (ROOM_PACKS.into(), "*".to_owned()),
                     (ROOM_PREVIEW_URLS.into(), String::new()),
                 ])
+                .with_room_list_response_commit_hook(mentions.hook())
                 .build()
                 .await
                 .map_err(EngineError::SyncService)?,
         );
-        let store_lock = store_lock.map(Arc::new);
-        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(),
@@ -374,6 +431,9 @@ impl Engine {
             stops,
             logouts: Arc::new(watch::Sender::new(Logouts::default())),
             _store_lock: store_lock,
+            mentions,
+            mentions_service: Some(mentions_service),
+            mentions_updates: Some(mentions_updates),
         };
         Ok((engine, handle, events))
     }
@@ -459,6 +519,17 @@ impl Engine {
 
     fn start_tasks(&mut self) {
         let queues = self.queues.take().expect("engine tasks start once");
+        if let Some(service) = self.mentions_service.take() {
+            self.tasks
+                .spawn(TaskContext::Watcher("mentions service"), service.run());
+        }
+        if let Some(updates) = self.mentions_updates.take() {
+            let events = self.port.event_sender();
+            self.tasks.spawn(
+                TaskContext::Watcher("mentions updates"),
+                crate::mentions::service::watch_updates(updates, events),
+            );
+        }
         let (incoming, incoming_verifications) = mpsc::unbounded_channel();
         self.verification_handler = Some(self.verification_handler(incoming));
         let client = &self.client;
@@ -754,9 +825,18 @@ impl Engine {
                     return None;
                 };
                 let current_user_id = client.user_id().map(ToOwned::to_owned);
-                self.tasks.spawn(TaskContext::Command("event context"), async move {
-                    reply.send(context::execute(room, current_user_id, command).await);
-                });
+                let media = self.media.clone();
+                self.tasks
+                    .spawn(TaskContext::Command("event context"), async move {
+                        reply.send(context::execute(room, current_user_id, media, command).await);
+                    });
+            }
+            Command::Mentions(command) => {
+                let mentions = self.mentions.clone();
+                self.tasks
+                    .spawn(TaskContext::Command("mentions command"), async move {
+                        reply.send(mentions.execute(command).await);
+                    });
             }
             Command::Media(MediaCommand::Upload(upload)) => self.upload(upload, reply),
             Command::Encryption(command) => enqueue(&self.encryption, Job { command, reply }),
@@ -1040,10 +1120,13 @@ impl Engine {
             self.client.remove_event_handler(handler);
         }
         self.port.close();
+        self.sync.stop().await;
+        if self.mentions_service.is_none() {
+            self.mentions.stop().await;
+        }
         self.tasks.shutdown().await;
         self.rooms.clear();
         self.media.clear().await;
-        self.sync.stop().await;
         self.port
             .connection_sender()
             .send_replace(ConnectionState::Stopped);

Modified file: src/lib.rs+9 additions−3 deletions@@ -3,6 +3,8 @@
 mod encryption;
 mod engine;
 mod error;
+mod mentions;
+mod mentions_model;
 #[cfg(feature = "mirror")]
 mod mirror;
 mod model;
@@ -41,6 +43,10 @@ pub use session_store::{EncryptedSessionStore, SessionStore};
 pub use engine::{Engine, EngineConfig, EngineError};
 pub use error::{Error, ErrorKind, ServerError};
 pub use imbl;
+pub use mentions_model::{
+    MentionCaptureState, MentionCoverage, MentionEntry, MentionGap, MentionKey, MentionReason,
+    MentionsBoundary, MentionsCommand, MentionsPage, MentionsUpdate, SavedMentionContext,
+};
 #[cfg(feature = "mirror")]
 pub use mirror::{
     Mirror, MirrorHandle, SessionStatus, State, StateChange, Subscription, TimelineChange,
@@ -49,7 +55,8 @@ pub use mirror::{
 pub use model::{
     AccountCommand, AttachmentEncryption, AttachmentUpload, Change, Command, CommandOutput,
     ConnectionState, CreateRoomOptions, EncryptionCommand, EncryptionState, EngineErrorKind,
-    EngineFailure, Event, EventRef, HistoryState, ImagePack, ImagePackSource, ImagePacks,
+    EngineFailure, Event, EventContext, EventContextCommand, EventContextDirection,
+    EventContextPage, EventRef, HistoryState, ImagePack, ImagePackSource, ImagePacks,
     KeyBackupState, LatestEvent, LifecycleCommand, LinkPreview, LinkPreviewImage, Media,
     MediaCommand, MediaDescriptor, MediaFile, MediaId, MediaKind, MediaLocation, MediaSize,
     MemberFilter, MemberMembership, MemberSummary, MembershipChange, Message, MessageContent,
@@ -62,8 +69,7 @@ pub use model::{
     Sender, SpaceChild, Termination, ThreadSummary, TimelineCommand, TimelineContent, TimelineDiff,
     TimelineDiffError, TimelineEvent, TimelineId, TimelineItem, TimelineItemId, TypingState,
     UploadDetails, UploadOutcome, UploadThumbnail, UtdCause, VerificationAction,
-    VerificationFailure, VerificationState, VerificationTarget, EventContext, EventContextCommand,
-    EventContextDirection, EventContextPage,
+    VerificationFailure, VerificationState, VerificationTarget,
 };
 pub use ruma;
 pub use transport::{ClientHandle, EventStream, Pending, SpaceHierarchy};

Added file: src/mentions/mod.rs+6

@@ -0,0 +1,6 @@

1+pub(crate) mod service;

2+mod state;

3+#[cfg(test)]

4+mod state_tests;

5+#[cfg(any(feature = "sqlite", feature = "indexeddb"))]

6+pub(crate) mod store;

Added file: src/mentions/service.rs+1314 additions@@ -0,0 +1,1314 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    sync::Arc,
+    time::Duration,
+};
+
+use futures_util::{StreamExt, stream::FuturesUnordered};
+use matrix_sdk::{
+    Client, RoomState,
+    sliding_sync::{ResponseCommitBatch, ResponseCommitHook},
+};
+use ruma::{
+    OwnedRoomId, OwnedUserId,
+    events::{AnySyncTimelineEvent, room::encrypted::OriginalSyncRoomEncryptedEvent},
+    serde::Raw,
+};
+use serde_json::Value;
+use tokio::sync::{mpsc, oneshot, watch};
+
+use super::state::{Candidate, Data, SavedEvent, Window, id, invalid, now};
+use crate::{
+    CommandOutput, EngineConfig, Error, ErrorKind, Event, MentionCaptureState, MentionEntry,
+    MentionGap, MentionKey, MentionReason, MentionsCommand, MentionsPage, MentionsUpdate,
+    TimelineContent, TimelineItem,
+    engine::{MediaService, MentionsStore, context, executor::EngineBoxFuture},
+    normalise::{MediaRegistration, normalise_observed},
+    transport::EventSender,
+};
+
+#[cfg(all(test, feature = "sqlite"))]
+#[path = "service_tests.rs"]
+mod tests;
+
+#[derive(Clone)]
+pub(crate) struct Handle(mpsc::Sender<Request>);
+
+enum Request {
+    Batch(ResponseCommitBatch, oneshot::Sender<Result<(), Error>>),
+    Command(
+        MentionsCommand,
+        oneshot::Sender<Result<CommandOutput, Error>>,
+    ),
+    Stop(oneshot::Sender<()>),
+}
+
+pub(crate) struct Service {
+    client: Client,
+    account: OwnedUserId,
+    media: Arc<MediaService>,
+    store: Option<MentionsStore>,
+    data: Data,
+    config: EngineConfig,
+    requests: mpsc::Receiver<Request>,
+    updates: watch::Sender<MentionsPage>,
+    recovery_budget: usize,
+    latest_scan: bool,
+    recovery_retry: u64,
+}
+
+enum Work {
+    Capture(
+        String,
+        u64,
+        Result<(crate::EventContext, Vec<MediaRegistration>, Vec<Value>), Error>,
+    ),
+    Candidate(String, Result<Value, Error>),
+    History(
+        bool,
+        Option<String>,
+        Result<ruma::api::client::push::get_notifications::v3::Response, Error>,
+    ),
+}
+
+impl Handle {
+    pub(crate) fn hook(&self) -> ResponseCommitHook {
+        let handle = self.clone();
+        ResponseCommitHook::new(move |batch| {
+            let handle = handle.clone();
+            async move {
+                let (reply, response) = oneshot::channel();
+                handle
+                    .0
+                    .send(Request::Batch(batch, reply))
+                    .await
+                    .map_err(|_| "mentions service stopped".to_owned())?;
+                response
+                    .await
+                    .map_err(|_| "mentions commit acknowledgement dropped".to_owned())?
+                    .map_err(|error| error.to_string())
+            }
+        })
+    }
+
+    pub(crate) async fn execute(&self, command: MentionsCommand) -> Result<CommandOutput, Error> {
+        let (reply, response) = oneshot::channel();
+        self.0
+            .send(Request::Command(command, reply))
+            .await
+            .map_err(|_| Error::interrupted())?;
+        response.await.map_err(|_| Error::interrupted())?
+    }
+
+    pub(crate) async fn stop(&self) {
+        let (reply, response) = oneshot::channel();
+        if self.0.send(Request::Stop(reply)).await.is_ok() {
+            let _ = response.await;
+        }
+    }
+}
+
+impl Service {
+    pub(crate) async fn new(
+        client: Client,
+        media: Arc<MediaService>,
+        store: Option<MentionsStore>,
+        config: EngineConfig,
+    ) -> Result<(Handle, Self, watch::Receiver<MentionsPage>), Error> {
+        let account = client
+            .user_id()
+            .ok_or_else(|| {
+                Error::new(
+                    ErrorKind::Unauthenticated,
+                    "mentions require an authenticated account",
+                )
+            })?
+            .to_owned();
+        #[cfg(any(feature = "sqlite", feature = "indexeddb"))]
+        let data: Data = store
+            .as_ref()
+            .map(|store| store.read("inbox"))
+            .transpose()?
+            .flatten()
+            .unwrap_or_default();
+        #[cfg(not(any(feature = "sqlite", feature = "indexeddb")))]
+        let data = Data::default();
+        #[cfg(any(feature = "sqlite", feature = "indexeddb"))]
+        if store
+            .as_ref()
+            .is_some_and(|store| store.revision() != data.revision)
+        {
+            return Err(Error::new(
+                ErrorKind::Store,
+                "mentions revision does not match its checkpoint",
+            ));
+        }
+        let page = data.page(&account, None, 50)?;
+        media
+            .register(
+                page.entries
+                    .iter()
+                    .filter_map(|entry| data.events.get(&id(&entry.key)))
+                    .flat_map(|event| event.media.clone())
+                    .collect(),
+            )
+            .await;
+        let (updates, receiver) = watch::channel(page);
+        let (sender, requests) = mpsc::channel(config.command_capacity.max(1));
+        Ok((
+            Handle(sender),
+            Self {
+                client,
+                account,
+                media,
+                store,
+                data,
+                config,
+                requests,
+                updates,
+                recovery_budget: 20,
+                latest_scan: true,
+                recovery_retry: 0,
+            },
+            receiver,
+        ))
+    }
+
+    async fn save(&mut self, mut next: Data) -> Result<(), Error> {
+        next.revision = self
+            .data
+            .revision
+            .checked_add(1)
+            .ok_or_else(|| invalid("mentions revision exhausted"))?;
+        next.bound(
+            self.config.max_mentions_entries,
+            self.config.max_mention_context_events,
+            self.config.max_mention_candidates,
+        );
+        #[cfg(any(feature = "sqlite", feature = "indexeddb"))]
+        if let Some(store) = &mut self.store {
+            loop {
+                let value = serde_json::to_value(&next).map_err(|error| {
+                    Error::with_source(
+                        ErrorKind::Store,
+                        "encoding the mentions inbox failed",
+                        error,
+                    )
+                })?;
+                match store
+                    .commit(
+                        self.data.revision,
+                        vec![super::store::Write::Set("inbox".to_owned(), value)],
+                    )
+                    .await
+                {
+                    Ok(_) => break,
+                    Err(error)
+                        if error.message == "mentions storage limit exceeded"
+                            && next.evict_one() => {}
+                    Err(error) => return Err(error),
+                }
+            }
+        }
+        self.data = next;
+        let page = self.data.page(&self.account, None, 50)?;
+        self.media
+            .register(
+                page.entries
+                    .iter()
+                    .filter_map(|entry| self.data.events.get(&id(&entry.key)))
+                    .flat_map(|event| event.media.clone())
+                    .collect(),
+            )
+            .await;
+        self.updates.send_replace(page);
+        Ok(())
+    }
+
+    async fn command(&mut self, command: MentionsCommand) -> Result<CommandOutput, Error> {
+        match command {
+            MentionsCommand::Page { cursor, limit } => {
+                let page = self.data.page(&self.account, cursor.as_deref(), limit)?;
+                self.media
+                    .register(
+                        page.entries
+                            .iter()
+                            .filter_map(|entry| self.data.events.get(&id(&entry.key)))
+                            .flat_map(|event| event.media.clone())
+                            .collect(),
+                    )
+                    .await;
+                Ok(CommandOutput::MentionsPage(page))
+            }
+            MentionsCommand::Context(key) => {
+                let (context, media) = self.data.context(&key)?;
+                self.media.register(media).await;
+                Ok(CommandOutput::MentionContext(context))
+            }
+            MentionsCommand::RetryContext(key) => {
+                let room = self
+                    .client
+                    .get_room(&key.room_id)
+                    .filter(|room| room.state() == RoomState::Joined)
+                    .ok_or_else(|| {
+                        Error::new(
+                            ErrorKind::Forbidden,
+                            "saved context cannot be refetched after leaving the room",
+                        )
+                    })?;
+                drop(room);
+                let mut next = self.data.clone();
+                let entry = next
+                    .entries
+                    .get_mut(&id(&key))
+                    .ok_or_else(|| Error::new(ErrorKind::EventNotFound, "mention was not found"))?;
+                entry.capture = MentionCaptureState::Pending;
+                entry.revision = self.data.revision + 1;
+                next.windows.entry(id(&key)).or_insert(Window {
+                    before: Vec::new(),
+                    target: Some(id(&key)),
+                    after: Vec::new(),
+                    start: None,
+                    end: None,
+                });
+                self.save(next).await?;
+                let (context, media) = self.data.context(&key)?;
+                self.media.register(media).await;
+                Ok(CommandOutput::MentionContext(context))
+            }
+            MentionsCommand::SetRead { keys, read } => {
+                let mut next = self.data.clone();
+                for key in keys {
+                    if let Some(entry) = next.entries.get_mut(&id(&key)) {
+                        entry.read = read;
+                        entry.revision = self.data.revision + 1;
+                    }
+                }
+                self.save(next).await?;
+                Ok(CommandOutput::Done)
+            }
+            MentionsCommand::ReadThrough(boundary) => {
+                if boundary.account != self.account || boundary.revision > self.data.revision {
+                    return Err(invalid("invalid mentions read boundary"));
+                }
+                let mut next = self.data.clone();
+                for entry in next
+                    .entries
+                    .values_mut()
+                    .filter(|entry| entry.discovery_revision <= boundary.revision)
+                {
+                    entry.read = true;
+                    entry.revision = self.data.revision + 1;
+                }
+                self.save(next).await?;
+                Ok(CommandOutput::Done)
+            }
+            MentionsCommand::Recover => {
+                self.recovery_budget = 20;
+                self.latest_scan = true;
+                self.recovery_retry = 0;
+                let mut next = self.data.clone();
+                next.coverage.recovering = true;
+                next.coverage.historical_supported = None;
+                self.save(next).await?;
+                Ok(CommandOutput::Done)
+            }
+        }
+    }
+
+    fn gap(data: &mut Data, room_id: Option<OwnedRoomId>, reason: &str, token: Option<String>) {
+        if !data
+            .coverage
+            .gaps
+            .iter()
+            .any(|gap| gap.room_id == room_id && gap.reason == reason && gap.token == token)
+        {
+            data.coverage.gaps.push(MentionGap {
+                room_id,
+                reason: reason.to_owned(),
+                token,
+            });
+            if data.coverage.gaps.len() > 128 {
+                data.coverage.gaps.remove(0);
+                data.coverage.truncated = true;
+            }
+        }
+    }
+
+    async fn batch(&mut self, batch: ResponseCommitBatch) -> Result<(), Error> {
+        let mut next = self.data.clone();
+        if next.checkpoints.get(&batch.connection_id) == Some(&batch.next_pos) {
+            return Ok(());
+        }
+        if next.checkpoints.get(&batch.connection_id) != batch.previous_pos.as_ref() {
+            Self::gap(
+                &mut next,
+                None,
+                "sync checkpoint continuity is unknown",
+                None,
+            );
+        }
+        for (room_id, raw) in &batch.raw_rooms {
+            if raw.limited || !next.observed_rooms.contains(room_id) {
+                Self::gap(
+                    &mut next,
+                    Some(room_id.clone()),
+                    if raw.limited {
+                        "limited sync timeline"
+                    } else {
+                        "initial room history is incomplete"
+                    },
+                    raw.prev_batch.clone(),
+                );
+            }
+        }
+        let room_ids: BTreeSet<_> = batch
+            .raw_rooms
+            .keys()
+            .chain(batch.response.rooms.joined.keys())
+            .cloned()
+            .collect();
+        for room_id in &room_ids {
+            if !self
+                .client
+                .get_room(room_id)
+                .is_some_and(|room| room.state() == RoomState::Joined)
+            {
+                continue;
+            }
+            next.observed_rooms.insert(room_id.clone());
+            let mut observed = BTreeMap::new();
+            if let Some(raw) = batch.raw_rooms.get(room_id) {
+                for event in &raw.timeline {
+                    let value: Value =
+                        serde_json::from_str(event.json().get()).map_err(|error| {
+                            Error::with_source(ErrorKind::Invalid, "invalid observed event", error)
+                        })?;
+                    if let Some(event_id) = value["event_id"].as_str() {
+                        observed.insert(event_id.to_owned(), value);
+                    }
+                }
+            }
+            if let Some(update) = batch.response.rooms.joined.get(room_id) {
+                for event in &update.timeline.events {
+                    let value: Value =
+                        serde_json::from_str(event.raw().json().get()).map_err(|error| {
+                            Error::with_source(ErrorKind::Invalid, "invalid observed event", error)
+                        })?;
+                    if let Some(event_id) = value["event_id"].as_str() {
+                        observed.insert(event_id.to_owned(), value);
+                    }
+                }
+            }
+            let mut observed: Vec<_> = observed.into_values().collect();
+            observed.sort_by_key(|value| value["origin_server_ts"].as_u64().unwrap_or(0));
+            for value in observed {
+                self.observe(&mut next, room_id, value).await?;
+            }
+        }
+        for room_id in batch.response.rooms.left.keys() {
+            Self::gap(
+                &mut next,
+                Some(room_id.clone()),
+                "room left, retained context is read only",
+                None,
+            );
+            next.candidates
+                .retain(|_, candidate| &candidate.room_id != room_id);
+            for entry in next
+                .entries
+                .values_mut()
+                .filter(|entry| &entry.key.room_id == room_id)
+            {
+                entry.capture = MentionCaptureState::Unavailable;
+                entry.revision = next.revision + 1;
+            }
+        }
+        let reevaluate: Vec<_> = next
+            .entries
+            .values()
+            .filter(|entry| room_ids.contains(&entry.key.room_id))
+            .filter_map(|entry| {
+                next.events
+                    .get(&id(&entry.key))
+                    .and_then(|event| event.raw.clone())
+                    .map(|raw| (entry.key.room_id.clone(), raw))
+            })
+            .collect();
+        for (room_id, raw) in reevaluate {
+            self.observe(&mut next, &room_id, raw).await?;
+        }
+        self.filter_ignored(&mut next).await;
+        next.checkpoints.insert(batch.connection_id, batch.next_pos);
+        self.save(next).await
+    }
+
+    async fn filter_ignored(&self, next: &mut Data) {
+        let mut removed = Vec::new();
+        for (key, entry) in &next.entries {
+            if let TimelineItem::Event(event) = &entry.event {
+                if self.client.is_user_ignored(&event.sender.user_id).await {
+                    removed.push(key.clone());
+                }
+            }
+        }
+        for key in removed {
+            next.entries.remove(&key);
+            next.windows.remove(&key);
+        }
+        next.collect_events();
+    }
+
+    async fn observe(
+        &self,
+        data: &mut Data,
+        room_id: &OwnedRoomId,
+        mut value: Value,
+    ) -> Result<(), Error> {
+        let Some(event_id) = value["event_id"]
+            .as_str()
+            .and_then(|value| value.parse().ok())
+        else {
+            return Ok(());
+        };
+        let key = MentionKey {
+            room_id: room_id.clone(),
+            event_id,
+        };
+        let identity = id(&key);
+        let Some(timestamp) = value["origin_server_ts"].as_u64() else {
+            return Ok(());
+        };
+        data.coverage.earliest_timestamp_ms = Some(
+            data.coverage
+                .earliest_timestamp_ms
+                .map_or(timestamp, |old| old.min(timestamp)),
+        );
+        if value["type"] == "m.room.redaction" {
+            if let Some(target) = value["redacts"]
+                .as_str()
+                .or_else(|| value["content"]["redacts"].as_str())
+                .and_then(|value| value.parse().ok())
+            {
+                let target = id(&MentionKey {
+                    room_id: room_id.clone(),
+                    event_id: target,
+                });
+                data.redacted.insert(target.clone(), timestamp);
+                data.entries.remove(&target);
+                data.windows.remove(&target);
+                data.candidates.remove(&target);
+                data.edits.remove(&target);
+                data.candidates.retain(|_, candidate| {
+                    candidate.room_id != *room_id
+                        || candidate.raw["content"]["m.relates_to"]["event_id"].as_str()
+                            != target.split_once('\n').map(|(_, event)| event)
+                });
+                if let Some(saved) = data.events.get_mut(&target) {
+                    redact(saved);
+                }
+                data.touch_contexts(&target);
+            }
+            return Ok(());
+        }
+        if data.redacted.contains_key(&identity)
+            || value["unsigned"].get("redacted_because").is_some()
+        {
+            data.redacted.insert(identity.clone(), timestamp);
+            data.entries.remove(&identity);
+            data.windows.remove(&identity);
+            data.candidates.remove(&identity);
+            if let Some(saved) = data.events.get_mut(&identity) {
+                redact(saved);
+            }
+            data.touch_contexts(&identity);
+            return Ok(());
+        }
+        if value["content"]["m.relates_to"]["rel_type"] == "m.replace" {
+            if let Some(target) = value["content"]["m.relates_to"]["event_id"]
+                .as_str()
+                .and_then(|value| value.parse().ok())
+            {
+                let target = id(&MentionKey {
+                    room_id: room_id.clone(),
+                    event_id: target,
+                });
+                if data.redacted.contains_key(&target) {
+                    return Ok(());
+                }
+                let newer = data.edits.get(&target).is_none_or(|old| {
+                    (old["origin_server_ts"].as_u64(), old["event_id"].as_str())
+                        < (Some(timestamp), value["event_id"].as_str())
+                });
+                if newer {
+                    if let Some(original) =
+                        data.events.get(&target).and_then(|saved| saved.raw.clone())
+                    {
+                        if original["sender"] != value["sender"] {
+                            return Ok(());
+                        }
+                        data.edits.insert(target.clone(), value.clone());
+                        value = edited(original, &value);
+                        return Box::pin(self.observe(data, room_id, value)).await;
+                    }
+                    data.candidates.insert(
+                        identity,
+                        Candidate {
+                            room_id: room_id.clone(),
+                            raw: value,
+                            attempts: 0,
+                            retry_at_ms: 0,
+                        },
+                    );
+                }
+            }
+            return Ok(());
+        }
+        if let Some(edit) = value["unsigned"]["m.relations"].get("m.replace").cloned() {
+            if edit["sender"] == value["sender"]
+                && edit["content"]["m.new_content"].is_object()
+                && edit["content"]["m.relates_to"]["event_id"]
+                    .as_str()
+                    .is_none_or(|target| target == key.event_id.as_str())
+                && edit["origin_server_ts"].as_u64().is_some()
+                && data.edits.get(&identity).is_none_or(|old| {
+                    (old["origin_server_ts"].as_u64(), old["event_id"].as_str())
+                        < (edit["origin_server_ts"].as_u64(), edit["event_id"].as_str())
+                })
+            {
+                data.edits.insert(identity.clone(), edit);
+            }
+        }
+        if let Some(edit) = data.edits.get(&identity) {
+            if value["sender"] == edit["sender"] {
+                value = edited(value, edit);
+            }
+        }
+        if let Some(edit) = value["unsigned"].get("macltok_edit").cloned() {
+            data.edits.insert(identity.clone(), edit);
+        }
+        if value["type"] == "m.room.encrypted" {
+            data.candidates.entry(identity).or_insert(Candidate {
+                room_id: room_id.clone(),
+                raw: value,
+                attempts: 0,
+                retry_at_ms: 0,
+            });
+            return Ok(());
+        }
+        let Some((item, media)) = normalise_observed(&value, Some(&self.account), &identity) else {
+            return Ok(());
+        };
+        self.supplement(data, &key, &item, &media, &value);
+        let (reasons, suppressed, unresolved) = self.classify(data, room_id, &value).await;
+        if unresolved {
+            data.candidates
+                .entry(identity.clone())
+                .or_insert(Candidate {
+                    room_id: room_id.clone(),
+                    raw: value.clone(),
+                    attempts: 0,
+                    retry_at_ms: now() + 30_000,
+                });
+        } else {
+            data.candidates.remove(&identity);
+        }
+        if reasons.is_empty() {
+            data.entries.remove(&identity);
+            data.windows.remove(&identity);
+            if data.events.contains_key(&identity) || data.edits.contains_key(&identity) {
+                data.events.insert(
+                    identity,
+                    SavedEvent {
+                        item,
+                        media,
+                        raw: Some(value),
+                    },
+                );
+            }
+            return Ok(());
+        }
+        let previous = data.entries.get(&identity);
+        let changed = previous.is_none_or(|entry| {
+            entry.event != item
+                || entry.reasons != reasons
+                || entry.notification_suppressed != suppressed
+        });
+        let entry = MentionEntry {
+            key,
+            timestamp_ms: timestamp,
+            discovered_at_ms: previous.map_or_else(now, |entry| entry.discovered_at_ms),
+            discovery_revision: previous
+                .map_or(data.revision + 1, |entry| entry.discovery_revision),
+            revision: if changed {
+                data.revision + 1
+            } else {
+                previous.unwrap().revision
+            },
+            event: item.clone(),
+            reasons,
+            read: previous.is_some_and(|entry| entry.read),
+            capture: previous.map_or(MentionCaptureState::Pending, |entry| {
+                if changed {
+                    MentionCaptureState::Pending
+                } else {
+                    entry.capture.clone()
+                }
+            }),
+            room_name: self.client.get_room(room_id).and_then(|room| room.name()),
+            notification_suppressed: suppressed,
+        };
+        data.entries.insert(identity.clone(), entry);
+        data.windows.entry(identity.clone()).or_insert(Window {
+            before: Vec::new(),
+            target: Some(identity.clone()),
+            after: Vec::new(),
+            start: None,
+            end: None,
+        });
+        data.events.insert(
+            identity,
+            SavedEvent {
+                item,
+                media,
+                raw: Some(value),
+            },
+        );
+        Ok(())
+    }
+
+    fn supplement(
+        &self,
+        data: &mut Data,
+        key: &MentionKey,
+        item: &TimelineItem,
+        media: &[MediaRegistration],
+        raw: &Value,
+    ) {
+        let TimelineItem::Event(event) = item else {
+            return;
+        };
+        let identity = id(key);
+        if data
+            .events
+            .get(&identity)
+            .is_some_and(|saved| saved.item != *item)
+        {
+            data.touch_contexts(&identity);
+        }
+        let mut retained = data.events.contains_key(&identity);
+        let saved_events = &data.events;
+        for (target, window) in &mut data.windows {
+            let Some(entry) = data.entries.get_mut(target) else {
+                continue;
+            };
+            if entry.key.room_id != key.room_id
+                || (entry.timestamp_ms, target.as_str()) >= (event.timestamp_ms, identity.as_str())
+                || window.after.contains(&identity)
+            {
+                continue;
+            }
+            let previous = window.after.clone();
+            window.after.push(identity.clone());
+            window.after.sort_by_key(|key| {
+                if key == &identity {
+                    (event.timestamp_ms, key.clone())
+                } else {
+                    (
+                        saved_events
+                            .get(key)
+                            .and_then(|saved| match &saved.item {
+                                TimelineItem::Event(event) => Some(event.timestamp_ms),
+                                _ => None,
+                            })
+                            .unwrap_or(0),
+                        key.clone(),
+                    )
+                }
+            });
+            window.after.truncate(10);
+            if window.after == previous {
+                continue;
+            }
+            window.end = None;
+            retained |= window.after.contains(&identity);
+            if entry.capture == MentionCaptureState::Partial
+                && window.after.len() == 10
+                && (window.before.len() == 10 || window.start.is_none())
+            {
+                entry.capture = MentionCaptureState::Ready;
+            }
+            entry.revision = data.revision + 1;
+        }
+        if retained {
+            data.events.insert(
+                identity,
+                SavedEvent {
+                    item: item.clone(),
+                    media: media.to_vec(),
+                    raw: Some(raw.clone()),
+                },
+            );
+        }
+    }
+
+    async fn classify(
+        &self,
+        data: &Data,
+        room_id: &OwnedRoomId,
+        value: &Value,
+    ) -> (Vec<MentionReason>, bool, bool) {
+        let Some(sender) = value["sender"]
+            .as_str()
+            .and_then(|sender| sender.parse::<OwnedUserId>().ok())
+        else {
+            return (vec![], false, false);
+        };
+        if sender == self.account
+            || self.client.is_user_ignored(&sender).await
+            || value["type"] != "m.room.message"
+        {
+            return (vec![], false, false);
+        }
+        let Some(room) = self
+            .client
+            .get_room(room_id)
+            .filter(|room| room.state() == RoomState::Joined)
+        else {
+            return (vec![], false, false);
+        };
+        let raw: Raw<AnySyncTimelineEvent> =
+            Raw::from_json_string(value.to_string()).expect("serialized event");
+        let actions = room.event_push_actions(&raw).await.ok().flatten();
+        let notify = actions.as_ref().is_some_and(|actions| {
+            actions
+                .iter()
+                .any(|action| matches!(action, ruma::push::Action::Notify))
+        });
+        let highlight = actions.as_ref().is_some_and(|actions| actions.iter().any(|action| matches!(action, ruma::push::Action::SetTweak(ruma::push::Tweak::Highlight(value)) if value != &ruma::push::HighlightTweakValue::No)));
+        let direct = value["content"]["m.mentions"]["user_ids"]
+            .as_array()
+            .is_some_and(|users| {
+                users
+                    .iter()
+                    .any(|user| user.as_str() == Some(self.account.as_str()))
+            });
+        let mut reasons = Vec::new();
+        if direct {
+            reasons.push(MentionReason::Direct);
+        }
+        let mut unresolved = false;
+        if let Some(reply) = value["content"]["m.relates_to"]["m.in_reply_to"]["event_id"]
+            .as_str()
+            .and_then(|value| value.parse().ok())
+        {
+            let target = data.events.get(&id(&MentionKey {
+                room_id: room_id.clone(),
+                event_id: reply,
+            }));
+            let reply_to_self = value["unsigned"]["macltok_reply_sender"].as_str() == Some(self.account.as_str()) || target.is_some_and(|target| matches!(&target.item, TimelineItem::Event(event) if event.sender.user_id == self.account));
+            if reply_to_self && (direct || (notify && highlight)) {
+                reasons.push(MentionReason::Reply);
+            } else if target.is_none()
+                && value["unsigned"]["macltok_reply_sender"].as_str().is_none()
+                && (direct || (notify && highlight))
+            {
+                unresolved = true;
+            }
+        }
+        if value["content"]["m.mentions"]["room"] == true {
+            match room.power_levels().await {
+                Ok(levels) if levels.user_can_trigger_room_notification(&sender) => {
+                    if notify && highlight {
+                        reasons.push(MentionReason::Room);
+                    } else if actions.is_none() {
+                        unresolved = true;
+                    }
+                }
+                Err(_) => unresolved = true,
+                _ => {}
+            }
+        }
+        (reasons, !notify, unresolved)
+    }
+
+    pub(crate) async fn run(mut self) {
+        let reports_client = self.client.clone();
+        let reports = reports_client
+            .event_cache()
+            .subscribe_to_decryption_reports();
+        futures_util::pin_mut!(reports);
+        let mut ignores = self.client.subscribe_to_ignore_user_list_changes();
+        let mut work: FuturesUnordered<EngineBoxFuture<'static, Work>> = FuturesUnordered::new();
+        let mut captures = BTreeSet::new();
+        let mut retries = BTreeSet::new();
+        let mut history = false;
+        let mut next_scan = now() + 60_000;
+        let mut tick = Box::pin(matrix_sdk::sleep::sleep(Duration::from_secs(1)));
+        loop {
+            self.schedule(&mut work, &mut captures, &mut retries, &mut history);
+            tokio::select! {
+                biased;
+                request = self.requests.recv() => match request {
+                    Some(Request::Stop(reply)) => { let _ = reply.send(()); return; }
+                    Some(Request::Batch(batch, reply)) => { let result = self.batch(batch).await; let _ = reply.send(result); }
+                    Some(Request::Command(command, reply)) => { let result = self.command(command).await; let _ = reply.send(result); }
+                    None => return,
+                },
+                Some(result) = work.next(), if !work.is_empty() => {
+                    let mut next = self.data.clone();
+                    let recovery = (self.latest_scan, self.recovery_budget);
+                    match result {
+                        Work::Capture(key, revision, result) => {
+                            captures.remove(&key);
+                            let observed = result.as_ref().ok().map(|(_, _, observed)| observed.clone()).unwrap_or_default();
+                            let room_id = next.entries.get(&key).filter(|entry| entry.revision == revision)
+                                .map(|entry| entry.key.room_id.clone())
+                                .filter(|room_id| self.client.get_room(room_id).is_some_and(|room| room.state() == RoomState::Joined));
+                            self.captured(&mut next, key, revision, result);
+                            if let Some(room_id) = room_id {
+                                for value in observed {
+                                    let identity = value["event_id"].as_str().map(|event_id| format!("{room_id}\n{event_id}"));
+                                    if identity.as_ref().is_some_and(|key| next.events.get(key).is_some_and(|event| event.raw.is_some())) { continue; }
+                                    self.observe(&mut next, &room_id, value).await.ok();
+                                }
+                            }
+                        }
+                        Work::Candidate(key, result) => {
+                            retries.remove(&key);
+                            if let Some(mut candidate) = next.candidates.remove(&key) {
+                                match result {
+                                    Ok(value) => {
+                                        if let Err(error) = self.observe(&mut next, &candidate.room_id, value).await { tracing::warn!(%error, "mention retry failed"); }
+                                        if let Some(unresolved) = next.candidates.get_mut(&key) { unresolved.attempts = candidate.attempts.saturating_add(1); unresolved.retry_at_ms = now() + (1000u64 << unresolved.attempts.min(8)); }
+                                    }
+                                    Err(error) => {
+                                        if candidate.raw["type"] != "m.room.encrypted" && (matches!(error.kind, ErrorKind::EventNotFound | ErrorKind::Forbidden) || error.server.as_ref().is_some_and(|server| matches!(server.status, 403 | 404))) {
+                                            Self::gap(&mut next, Some(candidate.room_id), "mention notification context is unavailable", None);
+                                        } else { candidate.attempts = candidate.attempts.saturating_add(1); candidate.retry_at_ms = retry_at(&error, 1000u64 << candidate.attempts.min(8)); next.candidates.insert(key, candidate); }
+                                    }
+                                }
+                            }
+                        }
+                        Work::History(latest, from, result) => {
+                            history = false; self.recovery_budget = self.recovery_budget.saturating_sub(1);
+                            match result {
+                                Ok(page) => {
+                                    next.coverage.historical_supported = Some(true);
+                                    let mut reached_anchor = false;
+                                    for notification in page.notifications {
+                                        if let Some(event_id) = notification.event.get_field::<String>("event_id").ok().flatten() {
+                                            let identity = format!("{}\n{}", notification.room_id, event_id);
+                                            if latest && from.is_none() && next.latest_head.is_none() { next.latest_head = Some(identity.clone()); }
+                                            if latest && next.latest_anchor.as_ref() == Some(&identity) { reached_anchor = true; break; }
+                                        }
+                                        if self.client.get_room(&notification.room_id).is_some_and(|room| room.state() == RoomState::Joined) {
+                                        if let Ok(value) = serde_json::from_str(notification.event.json().get()) { let _ = self.observe(&mut next, &notification.room_id, value).await; }
+                                    }}
+                                    let token = page.next_token.filter(|token| Some(token) != from.as_ref() && !reached_anchor);
+                                    if latest { next.latest_cursor = token.clone(); if token.is_none() { self.latest_scan = false; next.latest_anchor = next.latest_head.take().or(next.latest_anchor); } }
+                                    else { next.history_cursor = token.clone(); next.history_exhausted = token.is_none(); }
+                                }
+                                Err(error) => {
+                                    if error.server.as_ref().is_some_and(|server| matches!(server.status, 404 | 405 | 501)) { next.coverage.historical_supported = Some(false); self.recovery_budget = 0; }
+                                    if error.server.as_ref().is_some_and(|server| server.status == 400) {
+                                        if latest { next.latest_cursor = None; next.latest_head = None; } else { next.history_cursor = None; }
+                                    }
+                                    Self::gap(&mut next, None, "notification history could not be recovered", from);
+                                    self.recovery_retry = retry_at(&error, 60_000);
+                                }
+                            }
+                            next.coverage.recovering = self.recovery_budget > 0 && (self.latest_scan || !next.history_exhausted) && next.coverage.historical_supported != Some(false);
+                        }
+                    }
+                    if let Err(error) = self.save(next).await { tracing::error!(%error, "saving mention background work failed"); self.latest_scan = recovery.0; self.recovery_budget = recovery.1; self.recovery_retry = now() + 60_000; }
+                }
+                Some(_) = reports.next() => { for candidate in self.data.candidates.values_mut() { candidate.retry_at_ms = 0; } }
+                Some(_) = ignores.next() => {
+                    let mut next = self.data.clone(); self.filter_ignored(&mut next).await;
+                    if let Err(error) = self.save(next).await { tracing::error!(%error, "saving ignored mention removals failed"); }
+                }
+                () = &mut tick => {
+                    tick = Box::pin(matrix_sdk::sleep::sleep(Duration::from_secs(1)));
+                    if now() >= next_scan && !history { self.recovery_budget = 20; self.latest_scan = true; next_scan = now() + 60_000; }
+                }
+            }
+        }
+    }
+
+    fn schedule(
+        &mut self,
+        work: &mut FuturesUnordered<EngineBoxFuture<'static, Work>>,
+        captures: &mut BTreeSet<String>,
+        retries: &mut BTreeSet<String>,
+        history: &mut bool,
+    ) {
+        for (key, entry) in self.data.entries.iter().filter(|(_, entry)| matches!(entry.capture, MentionCaptureState::Pending) || matches!(entry.capture, MentionCaptureState::Failed {retry_at_ms, ..} if retry_at_ms <= now())).take(128) {
+            if captures.len() >= 2 { break; }
+            if captures.contains(key) { continue; }
+            let Some(room) = self.client.get_room(&entry.key.room_id).filter(|room| room.state() == RoomState::Joined) else { continue; };
+            captures.insert(key.clone());
+            let key = key.clone(); let event_id = entry.key.event_id.clone(); let account = self.account.clone(); let revision = entry.revision;
+            work.push(Box::pin(async move { Work::Capture(key, revision, context::capture(room, Some(account), event_id, 10, 10).await) }));
+        }
+        for (key, candidate) in &self.data.candidates {
+            if retries.len() >= 2 {
+                break;
+            }
+            if candidate.retry_at_ms > now() || retries.contains(key) {
+                continue;
+            }
+            let Some(room) = self
+                .client
+                .get_room(&candidate.room_id)
+                .filter(|room| room.state() == RoomState::Joined)
+            else {
+                continue;
+            };
+            let key = key.clone();
+            let candidate = candidate.clone();
+            let key_for_work = key.clone();
+            retries.insert(key);
+            work.push(Box::pin(async move {
+                let result = async {
+                    if candidate.raw["type"] == "m.room.encrypted" {
+                        let raw: Raw<OriginalSyncRoomEncryptedEvent> =
+                            Raw::from_json_string(candidate.raw.to_string()).map_err(|error| {
+                                Error::with_source(
+                                    ErrorKind::Invalid,
+                                    "invalid encrypted mention candidate",
+                                    error,
+                                )
+                            })?;
+                        let event = room.decrypt_event(&raw, None).await.map_err(|error| {
+                            Error::from_sdk("decrypting a mention candidate failed", error)
+                        })?;
+                        let value: Value =
+                            serde_json::from_str(event.raw().json().get()).map_err(|error| {
+                                Error::with_source(
+                                    ErrorKind::Invalid,
+                                    "invalid decrypted mention",
+                                    error,
+                                )
+                            })?;
+                        if value["type"] == "m.room.encrypted" {
+                            return Err(Error::new(
+                                ErrorKind::Encryption,
+                                "mention candidate still awaits keys",
+                            ));
+                        }
+                        return Ok(value);
+                    }
+                    let target = candidate.raw["content"]["m.relates_to"]["event_id"]
+                        .as_str()
+                        .filter(|_| {
+                            candidate.raw["content"]["m.relates_to"]["rel_type"] == "m.replace"
+                        });
+                    if let Some(target) =
+                        target.and_then(|target| target.parse::<ruma::OwnedEventId>().ok())
+                    {
+                        let event = room.event(&target, None).await.map_err(|error| {
+                            Error::from_sdk("fetching an edited mention failed", error)
+                        })?;
+                        let original: Value = serde_json::from_str(event.raw().json().get())
+                            .map_err(|error| {
+                                Error::with_source(
+                                    ErrorKind::Invalid,
+                                    "invalid edited mention",
+                                    error,
+                                )
+                            })?;
+                        if original["sender"] == candidate.raw["sender"] {
+                            let mut original = edited(original, &candidate.raw);
+                            original["unsigned"]["macltok_edit"] = candidate.raw;
+                            return Ok(original);
+                        }
+                        return Err(Error::new(
+                            ErrorKind::Forbidden,
+                            "an edit belongs to a different sender",
+                        ));
+                    }
+                    let mut value = candidate.raw;
+                    if let Some(target) =
+                        value["content"]["m.relates_to"]["m.in_reply_to"]["event_id"]
+                            .as_str()
+                            .and_then(|target| target.parse::<ruma::OwnedEventId>().ok())
+                    {
+                        let event = room.event(&target, None).await.map_err(|error| {
+                            Error::from_sdk("fetching a mention reply target failed", error)
+                        })?;
+                        let target: Value = serde_json::from_str(event.raw().json().get())
+                            .map_err(|error| {
+                                Error::with_source(
+                                    ErrorKind::Invalid,
+                                    "invalid mention reply target",
+                                    error,
+                                )
+                            })?;
+                        value["unsigned"]["macltok_reply_sender"] = target["sender"].clone();
+                    }
+                    Ok(value)
+                }
+                .await;
+                Work::Candidate(key_for_work, result)
+            }));
+        }
+        if !*history
+            && self.recovery_budget > 0
+            && now() >= self.recovery_retry
+            && (self.latest_scan || !self.data.history_exhausted)
+            && self.data.coverage.historical_supported != Some(false)
+        {
+            *history = true;
+            let latest = self.latest_scan;
+            let from = if latest {
+                self.data.latest_cursor.clone()
+            } else {
+                self.data.history_cursor.clone()
+            };
+            let client = self.client.clone();
+            work.push(Box::pin(async move {
+                let mut request = ruma::api::client::push::get_notifications::v3::Request::new();
+                request.from = from.clone();
+                request.limit = Some(ruma::uint!(50));
+                let result = client.send(request).await.map_err(|error| {
+                    Error::from_sdk("fetching mention history failed", error.into())
+                });
+                Work::History(latest, from, result)
+            }));
+        }
+    }
+
+    fn captured(
+        &self,
+        data: &mut Data,
+        key: String,
+        revision: u64,
+        result: Result<(crate::EventContext, Vec<MediaRegistration>, Vec<Value>), Error>,
+    ) {
+        let Some(entry) = data.entries.get(&key) else {
+            return;
+        };
+        if entry.revision != revision {
+            return;
+        }
+        let room_id = entry.key.room_id.clone();
+        if !self
+            .client
+            .get_room(&room_id)
+            .is_some_and(|room| room.state() == RoomState::Joined)
+        {
+            return;
+        }
+        match result {
+            Ok((context, media, _)) => {
+                data.capture_attempts.remove(&key);
+                let live_after = data
+                    .windows
+                    .get(&key)
+                    .map(|window| window.after.clone())
+                    .unwrap_or_default();
+                let mut insert = |item: TimelineItem| -> Option<String> {
+                    let TimelineItem::Event(event) = &item else {
+                        return None;
+                    };
+                    let event_id = event.event_id.clone()?;
+                    let event_key = id(&MentionKey {
+                        room_id: room_id.clone(),
+                        event_id,
+                    });
+                    let registrations = media_for_item(&item, &media);
+                    let mut saved = SavedEvent {
+                        item,
+                        media: registrations,
+                        raw: None,
+                    };
+                    if let Some(existing) = data.events.get(&event_key) {
+                        saved = existing.clone();
+                    }
+                    if data.redacted.contains_key(&event_key) {
+                        redact(&mut saved);
+                    }
+                    data.events.insert(event_key.clone(), saved);
+                    Some(event_key)
+                };
+                let before: Vec<_> = context
+                    .events_before
+                    .into_iter()
+                    .filter_map(&mut insert)
+                    .collect();
+                let target = context.event.and_then(&mut insert);
+                let mut after: Vec<_> = context
+                    .events_after
+                    .into_iter()
+                    .filter_map(&mut insert)
+                    .collect();
+                let extended = live_after.iter().any(|key| !after.contains(key));
+                after.extend(live_after);
+                after.sort_by_key(|key| {
+                    (
+                        data.events
+                            .get(key)
+                            .and_then(|saved| match &saved.item {
+                                TimelineItem::Event(event) => Some(event.timestamp_ms),
+                                _ => None,
+                            })
+                            .unwrap_or(0),
+                        key.clone(),
+                    )
+                });
+                after.dedup();
+                after.truncate(10);
+                let entry = data.entries.get_mut(&key).unwrap();
+                entry.capture = if target.is_none() {
+                    MentionCaptureState::Unavailable
+                } else if after.len() < 10 || (before.len() < 10 && context.start_token.is_some()) {
+                    MentionCaptureState::Partial
+                } else {
+                    MentionCaptureState::Ready
+                };
+                entry.revision = data.revision + 1;
+                data.windows.insert(
+                    key,
+                    Window {
+                        before,
+                        target,
+                        after,
+                        start: context.start_token,
+                        end: if extended { None } else { context.end_token },
+                    },
+                );
+            }
+            Err(error) => {
+                let attempts = data.capture_attempts.entry(key.clone()).or_default();
+                *attempts = attempts.saturating_add(1);
+                let delay = (1000u64 << (*attempts).min(11)).min(3_600_000);
+                let entry = data.entries.get_mut(&key).unwrap();
+                entry.capture = if matches!(
+                    error.kind,
+                    ErrorKind::EventNotFound | ErrorKind::Forbidden | ErrorKind::RoomUnknown
+                ) || error
+                    .server
+                    .as_ref()
+                    .is_some_and(|server| matches!(server.status, 403 | 404))
+                {
+                    MentionCaptureState::Unavailable
+                } else {
+                    MentionCaptureState::Failed {
+                        message: error.to_string(),
+                        retry_at_ms: retry_at(&error, delay),
+                    }
+                };
+                entry.revision = data.revision + 1;
+            }
+        }
+    }
+}
+
+fn edited(mut original: Value, edit: &Value) -> Value {
+    original["content"] = edit["content"]["m.new_content"].clone();
+    original["unsigned"]["macltok_edited"] = Value::Bool(true);
+    original
+}
+
+fn retry_at(error: &Error, fallback_ms: u64) -> u64 {
+    let mut source = std::error::Error::source(error);
+    while let Some(current) = source {
+        if let Some(sdk) = current.downcast_ref::<matrix_sdk::Error>() {
+            if let Some(ruma::api::error::ErrorKind::LimitExceeded(data)) =
+                sdk.client_api_error_kind()
+            {
+                if let Some(delay) = data.retry_after {
+                    let delay = match delay {
+                        ruma::api::error::RetryAfter::Delay(delay) => delay,
+                        ruma::api::error::RetryAfter::DateTime(time) => time
+                            .duration_since(ruma::time::SystemTime::now())
+                            .unwrap_or_default(),
+                    };
+                    return now().saturating_add(
+                        u64::try_from(delay.as_millis())
+                            .unwrap_or(u64::MAX)
+                            .max(fallback_ms),
+                    );
+                }
+            }
+        }
+        source = current.source();
+    }
+    now().saturating_add(fallback_ms)
+}
+
+fn redact(event: &mut SavedEvent) {
+    if let TimelineItem::Event(item) = &mut event.item {
+        item.content = TimelineContent::Redacted;
+        item.reply_to = None;
+        item.reactions.clear();
+    }
+    event.media.clear();
+    event.raw = None;
+}
+
+fn media_for_item(
+    item: &TimelineItem,
+    registrations: &[MediaRegistration],
+) -> Vec<MediaRegistration> {
+    let TimelineItem::Event(event) = item else {
+        return Vec::new();
+    };
+    let mut ids = Vec::new();
+    match &event.content {
+        TimelineContent::Message(message) => {
+            ids.extend(message.media.iter().map(|media| &media.id));
+            ids.extend(
+                message
+                    .link_previews
+                    .iter()
+                    .filter_map(|preview| preview.image.as_ref().map(|image| &image.media_id)),
+            );
+        }
+        TimelineContent::Sticker { media, .. } => ids.push(&media.id),
+        _ => {}
+    }
+    registrations
+        .iter()
+        .filter(|registration| ids.contains(&&registration.id))
+        .cloned()
+        .collect()
+}
+
+pub(crate) async fn watch_updates(mut updates: watch::Receiver<MentionsPage>, events: EventSender) {
+    let mut previous: BTreeMap<String, MentionEntry> = BTreeMap::new();
+    loop {
+        let snapshot = updates.borrow_and_update().clone();
+        let current: BTreeMap<_, _> = snapshot
+            .entries
+            .iter()
+            .map(|entry| (id(&entry.key), entry.clone()))
+            .collect();
+        let upserts = current
+            .iter()
+            .filter(|(key, entry)| previous.get(*key) != Some(entry))
+            .map(|(_, entry)| entry.clone())
+            .collect();
+        let removed = previous
+            .iter()
+            .filter(|(key, _)| !current.contains_key(*key))
+            .map(|(_, entry)| entry.key.clone())
+            .collect();
+        previous = current;
+        if events
+            .send(Event::MentionsChanged(MentionsUpdate {
+                snapshot,
+                upserts,
+                removed,
+            }))
+            .await
+            .is_err()
+        {
+            return;
+        }
+        if updates.changed().await.is_err() {
+            return;
+        }
+    }
+}

Added file: src/mentions/service_tests.rs+454 additions@@ -0,0 +1,454 @@
+use std::{
+    sync::{
+        Arc,
+        atomic::{AtomicUsize, Ordering},
+    },
+    time::Duration,
+};
+
+use matrix_sdk::ruma::events::room::MediaSource;
+use matrix_sdk::{
+    ruma::{event_id, events::Mentions, push::Ruleset, room_id, user_id},
+    test_utils::mocks::MatrixMockServer,
+};
+use matrix_sdk_test::{JoinedRoomBuilder, event_factory::EventFactory};
+use rusqlite::Connection;
+use serde_json::json;
+use wiremock::{
+    Mock, ResponseTemplate,
+    matchers::{method, path, query_param, query_param_is_missing},
+};
+
+use super::super::store::{Account, MentionsStore};
+use super::*;
+use crate::{
+    MediaId, MediaKind, StoreConfig, TimelineContent, TimelineItem,
+    normalise::{MediaRegistration, MediaSourceInfo},
+};
+
+static STORES: AtomicUsize = AtomicUsize::new(0);
+const MAX_BYTES: usize = 64 * 1024 * 1024;
+
+fn config() -> StoreConfig {
+    let number = STORES.fetch_add(1, Ordering::Relaxed);
+    StoreConfig::sqlite(
+        std::env::temp_dir().join(format!(
+            "macltok-mentions-service-{}-{number}",
+            std::process::id()
+        )),
+        "service commit test passphrase",
+    )
+}
+
+fn account(client: &Client) -> Account {
+    Account {
+        homeserver: client.homeserver().to_string(),
+        user_id: client.user_id().unwrap().to_owned(),
+    }
+}
+
+async fn joined_client(
+    server: &MatrixMockServer,
+    room_id: &ruma::RoomId,
+) -> (Client, ruma::OwnedUserId) {
+    let client = server.client_builder().build().await;
+    let own_user = client.user_id().unwrap().to_owned();
+    let room_id = room_id.to_owned();
+    server
+        .mock_sync()
+        .ok_and_run(&client, {
+            let own_user = own_user.clone();
+            move |builder| {
+                let factory = EventFactory::new().room(&room_id);
+                builder.add_global_account_data(
+                    factory.push_rules(Ruleset::server_default(&own_user)),
+                );
+                builder.add_joined_room(
+                    JoinedRoomBuilder::new(&room_id).add_state_event(factory.member(&own_user)),
+                );
+            }
+        })
+        .await;
+    (client, own_user)
+}
+
+#[tokio::test]
+async fn failed_batch_keeps_inbox_and_checkpoint_at_the_same_commit_boundary() {
+    let server = MatrixMockServer::new().await;
+    let room_id = room_id!("!mentions:localhost");
+    let (client, own_user) = joined_client(&server, room_id).await;
+    let event = EventFactory::new()
+        .room(room_id)
+        .text_msg("commit boundary")
+        .mentions(Mentions::with_user_ids([own_user.clone()]))
+        .event_id(event_id!("$commit-boundary:localhost"))
+        .sender(user_id!("@bob:localhost"))
+        .into_raw_sync();
+    let raw_room = serde_json::from_value(json!({
+        "initial": true,
+        "timeline": [serde_json::to_value(event).unwrap()],
+    }))
+    .unwrap();
+    let batch = ResponseCommitBatch {
+        connection_id: "mentions-connection".to_owned(),
+        previous_pos: None,
+        next_pos: "mentions-position-1".to_owned(),
+        response: Default::default(),
+        raw_rooms: [(room_id.to_owned(), raw_room)].into(),
+    };
+    let config = config();
+    let store = MentionsStore::open(&config, account(&client), MAX_BYTES)
+        .await
+        .unwrap();
+    let media = Arc::new(MediaService::new(
+        client.clone(),
+        EngineConfig::default().max_media_bytes,
+        EngineConfig::default().max_media_sources,
+    ));
+    let (_handle, mut service, updates) =
+        Service::new(client, media, Some(store), EngineConfig::default())
+            .await
+            .unwrap();
+
+    let connection = Connection::open(config.mentions_location()).unwrap();
+    connection
+        .execute_batch(
+            "CREATE TRIGGER fail_mentions_inbox_insert BEFORE INSERT ON records WHEN NEW.key NOT IN ('!cipher', '!head') BEGIN SELECT RAISE(ABORT, 'injected inbox write failure'); END;
+             CREATE TRIGGER fail_mentions_inbox_update BEFORE UPDATE ON records WHEN OLD.key NOT IN ('!cipher', '!head') BEGIN SELECT RAISE(ABORT, 'injected inbox write failure'); END;",
+        )
+        .unwrap();
+
+    assert!(service.batch(batch.clone()).await.is_err());
+    assert_eq!(service.data.revision, 0);
+    assert!(service.data.entries.is_empty());
+    assert!(service.data.checkpoints.is_empty());
+    assert_eq!(updates.borrow().revision, 0);
+    assert!(updates.borrow().entries.is_empty());
+
+    let reopened = MentionsStore::open(&config, account(&service.client), MAX_BYTES)
+        .await
+        .unwrap();
+    assert_eq!(reopened.revision(), 0);
+    assert!(reopened.read::<Data>("inbox").unwrap().is_none());
+    drop(reopened);
+
+    connection
+        .execute_batch(
+            "DROP TRIGGER fail_mentions_inbox_insert;
+             DROP TRIGGER fail_mentions_inbox_update;",
+        )
+        .unwrap();
+    drop(connection);
+
+    service.batch(batch.clone()).await.unwrap();
+    assert_eq!(service.data.revision, 1);
+    assert_eq!(service.data.entries.len(), 1);
+    assert_eq!(
+        service.data.checkpoints.get("mentions-connection"),
+        Some(&batch.next_pos)
+    );
+    assert_eq!(updates.borrow().revision, 1);
+    assert_eq!(updates.borrow().entries.len(), 1);
+
+    let reopened = MentionsStore::open(&config, account(&service.client), MAX_BYTES)
+        .await
+        .unwrap();
+    let persisted: Data = reopened.read("inbox").unwrap().unwrap();
+    assert_eq!(reopened.revision(), 1);
+    assert_eq!(persisted.revision, 1);
+    assert_eq!(persisted.entries.len(), 1);
+    assert_eq!(
+        persisted.checkpoints.get("mentions-connection"),
+        Some(&batch.next_pos)
+    );
+    drop(reopened);
+
+    service.batch(batch).await.unwrap();
+    assert_eq!(service.data.revision, 1);
+    assert_eq!(service.store.as_ref().unwrap().revision(), 1);
+
+    drop(service);
+    config.delete().await.unwrap();
+}
+
+#[tokio::test]
+async fn service_recovers_notification_history_into_durable_unread_inbox() {
+    let server = MatrixMockServer::new().await;
+    let room_id = room_id!("!mentions:localhost");
+    let (client, own_user) = joined_client(&server, room_id).await;
+    let first = EventFactory::new()
+        .room(room_id)
+        .text_msg("history mention one")
+        .mentions(Mentions::with_user_ids([own_user.clone()]))
+        .event_id(event_id!("$history-one:localhost"))
+        .sender(user_id!("@bob:localhost"))
+        .into_raw_sync();
+    let second = EventFactory::new()
+        .room(room_id)
+        .text_msg("history mention two")
+        .mentions(Mentions::with_user_ids([own_user]))
+        .event_id(event_id!("$history-two:localhost"))
+        .sender(user_id!("@bob:localhost"))
+        .into_raw_sync();
+    let first = serde_json::from_str::<serde_json::Value>(first.json().get()).unwrap();
+    let second = serde_json::from_str::<serde_json::Value>(second.json().get()).unwrap();
+    Mock::given(method("GET"))
+        .and(path("/_matrix/client/v3/notifications"))
+        .and(query_param_is_missing("from"))
+        .and(query_param("limit", "50"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "notifications": [{
+                "actions": ["notify"],
+                "event": first,
+                "read": true,
+                "room_id": room_id.as_str(),
+                "ts": 1,
+            }],
+            "next_token": "history-page-two",
+        })))
+        .mount(server.server())
+        .await;
+    Mock::given(method("GET"))
+        .and(path("/_matrix/client/v3/notifications"))
+        .and(query_param("from", "history-page-two"))
+        .and(query_param("limit", "50"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "notifications": [{
+                "actions": ["notify"],
+                "event": second,
+                "read": true,
+                "room_id": room_id.as_str(),
+                "ts": 2,
+            }],
+        })))
+        .mount(server.server())
+        .await;
+
+    let config = config();
+    let store = MentionsStore::open(&config, account(&client), MAX_BYTES)
+        .await
+        .unwrap();
+    let media = Arc::new(MediaService::new(
+        client.clone(),
+        EngineConfig::default().max_media_bytes,
+        EngineConfig::default().max_media_sources,
+    ));
+    let (handle, service, mut updates) =
+        Service::new(client.clone(), media, Some(store), EngineConfig::default())
+            .await
+            .unwrap();
+    let service_task = tokio::spawn(service.run());
+
+    let discovered = tokio::time::timeout(Duration::from_secs(10), async {
+        loop {
+            let page = updates.borrow_and_update().clone();
+            if page.entries.len() == 2 && !page.coverage.recovering {
+                break page;
+            }
+            updates.changed().await.unwrap();
+        }
+    })
+    .await;
+    handle.stop().await;
+    service_task.await.unwrap();
+    let discovered = discovered.expect("notification history should be recovered");
+    assert_eq!(discovered.entries.len(), 2);
+    assert!(discovered.entries.iter().all(|entry| !entry.read));
+
+    let reopened = MentionsStore::open(&config, account(&client), MAX_BYTES)
+        .await
+        .unwrap();
+    let persisted: Data = reopened.read("inbox").unwrap().unwrap();
+    assert_eq!(reopened.revision(), persisted.revision);
+    assert_eq!(persisted.entries.len(), 2);
+    assert!(persisted.entries.values().all(|entry| !entry.read));
+    assert!(persisted.latest_cursor.is_none());
+    assert!(persisted.history_cursor.is_none());
+    drop(reopened);
+
+    config.delete().await.unwrap();
+}
+
+fn message_body(item: &TimelineItem) -> Option<&str> {
+    match item {
+        TimelineItem::Event(event) => match &event.content {
+            TimelineContent::Message(message) => Some(&message.body),
+            _ => None,
+        },
+        _ => None,
+    }
+}
+
+fn media_registration() -> MediaRegistration {
+    MediaRegistration {
+        id: MediaId::new("test-scope#image".to_owned()),
+        kind: MediaKind::Image,
+        full: MediaSourceInfo {
+            source: MediaSource::Plain(ruma::mxc_uri!("mxc://mentions.example/image").to_owned()),
+            mimetype: Some("image/png".to_owned()),
+            declared_size: Some(1234),
+        },
+        thumbnail: None,
+    }
+}
+
+#[tokio::test]
+async fn live_context_survives_capture_then_edit_and_redaction() {
+    let server = MatrixMockServer::new().await;
+    let room_id = room_id!("!mentions:localhost");
+    let (client, own_user) = joined_client(&server, room_id).await;
+    let mention = EventFactory::new()
+        .room(room_id)
+        .text_msg("direct mention")
+        .mentions(Mentions::with_user_ids([own_user]))
+        .event_id(event_id!("$live-mention:localhost"))
+        .sender(user_id!("@bob:localhost"))
+        .into_raw_sync();
+    let mut mention: serde_json::Value = serde_json::from_str(mention.json().get()).unwrap();
+    mention["origin_server_ts"] = json!(10);
+    let following = EventFactory::new()
+        .room(room_id)
+        .text_msg("following")
+        .event_id(event_id!("$live-following:localhost"))
+        .sender(user_id!("@bob:localhost"))
+        .into_raw_sync();
+    let mut following: serde_json::Value = serde_json::from_str(following.json().get()).unwrap();
+    following["origin_server_ts"] = json!(11);
+
+    let media = Arc::new(MediaService::new(
+        client.clone(),
+        EngineConfig::default().max_media_bytes,
+        EngineConfig::default().max_media_sources,
+    ));
+    let (_handle, mut service, _updates) =
+        Service::new(client, media, None, EngineConfig::default())
+            .await
+            .unwrap();
+    let room_id = room_id.to_owned();
+    let mention_key = MentionKey {
+        room_id: room_id.clone(),
+        event_id: event_id!("$live-mention:localhost").to_owned(),
+    };
+    let following_id = format!("{room_id}\n$live-following:localhost");
+    let mut data = Data::default();
+
+    service.observe(&mut data, &room_id, mention).await.unwrap();
+    service
+        .observe(&mut data, &room_id, following)
+        .await
+        .unwrap();
+
+    let mention_identity = id(&mention_key);
+    let entry = data.entries.get(&mention_identity).unwrap();
+    let revision = entry.revision;
+    let target = entry.event.clone();
+    service.captured(
+        &mut data,
+        mention_identity.clone(),
+        revision,
+        Ok((
+            crate::EventContext {
+                events_before: Vec::new(),
+                event: Some(target),
+                events_after: Vec::new(),
+                start_token: None,
+                end_token: None,
+            },
+            Vec::new(),
+            Vec::new(),
+        )),
+    );
+
+    assert_eq!(
+        data.entries[&mention_identity].capture,
+        MentionCaptureState::Partial
+    );
+    assert!(data.events.contains_key(&following_id));
+    let (saved, _) = data.context(&mention_key).unwrap();
+    let context = saved.context.unwrap();
+    assert_eq!(context.events_after.len(), 1);
+    assert_eq!(message_body(&context.events_after[0]), Some("following"));
+
+    let edit = json!({
+        "content": {
+            "body": "* edited following",
+            "m.new_content": {"body": "edited following", "msgtype": "m.text"},
+            "m.relates_to": {"event_id": "$live-following:localhost", "rel_type": "m.replace"},
+            "msgtype": "m.text"
+        },
+        "event_id": "$live-following-edit:localhost",
+        "origin_server_ts": 12,
+        "room_id": room_id.as_str(),
+        "sender": "@bob:localhost",
+        "type": "m.room.message"
+    });
+    service.observe(&mut data, &room_id, edit).await.unwrap();
+    let (saved, _) = data.context(&mention_key).unwrap();
+    let context = saved.context.unwrap();
+    assert_eq!(
+        message_body(&context.events_after[0]),
+        Some("edited following")
+    );
+
+    let saved_following = data.events.get_mut(&following_id).unwrap();
+    assert!(saved_following.raw.is_some());
+    saved_following.media.push(media_registration());
+    assert_eq!(saved_following.media.len(), 1);
+    let redaction = json!({
+        "content": {},
+        "event_id": "$live-following-redaction:localhost",
+        "origin_server_ts": 13,
+        "redacts": "$live-following:localhost",
+        "room_id": room_id.as_str(),
+        "sender": "@bob:localhost",
+        "type": "m.room.redaction"
+    });
+    service
+        .observe(&mut data, &room_id, redaction)
+        .await
+        .unwrap();
+
+    let saved_following = data.events.get(&following_id).unwrap();
+    assert!(matches!(
+        &saved_following.item,
+        TimelineItem::Event(event) if event.content == TimelineContent::Redacted
+    ));
+    assert!(saved_following.raw.is_none());
+    assert!(saved_following.media.is_empty());
+    let (saved, _) = data.context(&mention_key).unwrap();
+    let context = saved.context.unwrap();
+    assert!(matches!(
+        &context.events_after[0],
+        TimelineItem::Event(event) if event.content == TimelineContent::Redacted
+    ));
+    data.windows.remove(&mention_identity);
+    service.data = data;
+    let CommandOutput::MentionContext(context) = service
+        .command(MentionsCommand::RetryContext(mention_key))
+        .await
+        .unwrap()
+    else {
+        panic!("retry should return saved context");
+    };
+    assert_eq!(context.state, MentionCaptureState::Pending);
+    assert!(context.context.unwrap().event.is_some());
+}
+
+#[tokio::test]
+async fn explicit_recovery_rechecks_server_support() {
+    let server = MatrixMockServer::new().await;
+    let (client, _) = joined_client(&server, room_id!("!mentions:localhost")).await;
+    let config = EngineConfig::default();
+    let media = Arc::new(MediaService::new(
+        client.clone(),
+        config.max_media_bytes,
+        config.max_media_sources,
+    ));
+    let (_, mut service, _) = Service::new(client, media, None, config).await.unwrap();
+    service.data.coverage.historical_supported = Some(false);
+    service.recovery_budget = 0;
+    service.command(MentionsCommand::Recover).await.unwrap();
+    assert_eq!(service.data.coverage.historical_supported, None);
+    assert!(service.data.coverage.recovering);
+    assert_eq!(service.recovery_budget, 20);
+}

Added file: src/mentions/state.rs+283 additions@@ -0,0 +1,283 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use ruma::OwnedUserId;
+use serde_json::Value;
+
+use crate::{
+    Error, ErrorKind, EventContext, MentionCaptureState, MentionCoverage, MentionEntry, MentionKey,
+    MentionsBoundary, MentionsPage, SavedMentionContext, TimelineItem,
+    normalise::MediaRegistration,
+};
+
+#[derive(Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub(super) struct SavedEvent {
+    pub item: TimelineItem,
+    pub media: Vec<MediaRegistration>,
+    pub raw: Option<Value>,
+}
+
+#[derive(Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub(super) struct Candidate {
+    pub room_id: ruma::OwnedRoomId,
+    pub raw: Value,
+    pub attempts: u32,
+    pub retry_at_ms: u64,
+}
+
+#[derive(Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub(super) struct Window {
+    pub before: Vec<String>,
+    pub target: Option<String>,
+    pub after: Vec<String>,
+    pub start: Option<String>,
+    pub end: Option<String>,
+}
+
+#[derive(Clone, Default)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub(super) struct Data {
+    pub revision: u64,
+    pub entries: BTreeMap<String, MentionEntry>,
+    pub events: BTreeMap<String, SavedEvent>,
+    pub windows: BTreeMap<String, Window>,
+    pub capture_attempts: BTreeMap<String, u32>,
+    pub candidates: BTreeMap<String, Candidate>,
+    pub redacted: BTreeMap<String, u64>,
+    pub edits: BTreeMap<String, Value>,
+    pub coverage: MentionCoverage,
+    pub checkpoints: BTreeMap<String, String>,
+    pub observed_rooms: BTreeSet<ruma::OwnedRoomId>,
+    pub history_cursor: Option<String>,
+    pub history_exhausted: bool,
+    pub latest_cursor: Option<String>,
+    #[cfg_attr(feature = "serde", serde(default))]
+    pub latest_anchor: Option<String>,
+    #[cfg_attr(feature = "serde", serde(default))]
+    pub latest_head: Option<String>,
+}
+
+pub(super) fn id(key: &MentionKey) -> String {
+    format!("{}\n{}", key.room_id, key.event_id)
+}
+
+pub(super) fn now() -> u64 {
+    matrix_sdk::ruma::MilliSecondsSinceUnixEpoch::now()
+        .get()
+        .into()
+}
+
+pub(super) fn invalid(message: &'static str) -> Error {
+    Error::new(ErrorKind::Invalid, message)
+}
+
+impl Data {
+    pub fn touch_contexts(&mut self, identity: &str) {
+        for (key, window) in &self.windows {
+            if window.target.as_deref() == Some(identity)
+                || window
+                    .before
+                    .iter()
+                    .chain(&window.after)
+                    .any(|key| key == identity)
+            {
+                if let Some(entry) = self.entries.get_mut(key) {
+                    entry.revision = self.revision + 1;
+                }
+            }
+        }
+    }
+
+    pub fn page(
+        &self,
+        account: &OwnedUserId,
+        cursor: Option<&str>,
+        limit: u16,
+    ) -> Result<MentionsPage, Error> {
+        let (boundary, last) = if let Some(cursor) = cursor {
+            let value: Value =
+                serde_json::from_str(cursor).map_err(|_| invalid("invalid mentions cursor"))?;
+            if value["account"].as_str() != Some(account.as_str()) {
+                return Err(invalid("mentions cursor belongs to a different account"));
+            }
+            let boundary = value["revision"]
+                .as_u64()
+                .ok_or_else(|| invalid("invalid mentions cursor"))?;
+            let timestamp = value["timestamp"]
+                .as_u64()
+                .ok_or_else(|| invalid("invalid mentions cursor"))?;
+            let key = value["key"]
+                .as_str()
+                .ok_or_else(|| invalid("invalid mentions cursor"))?
+                .to_owned();
+            if boundary > self.revision {
+                return Err(invalid("mentions cursor is newer than this store"));
+            }
+            (boundary, Some((timestamp, key)))
+        } else {
+            (self.revision, None)
+        };
+        let mut entries: Vec<_> = self
+            .entries
+            .iter()
+            .filter(|(key, entry)| {
+                entry.discovery_revision <= boundary
+                    && last.as_ref().is_none_or(|last| {
+                        (entry.timestamp_ms, key.as_str()) < (last.0, last.1.as_str())
+                    })
+            })
+            .map(|(_, entry)| entry.clone())
+            .collect();
+        entries.sort_by(|a, b| (b.timestamp_ms, id(&b.key)).cmp(&(a.timestamp_ms, id(&a.key))));
+        let limit = usize::from(limit.clamp(1, 50));
+        let end_reached = entries.len() <= limit;
+        entries.truncate(limit);
+        let next_cursor = if end_reached {
+            None
+        } else {
+            entries.last().map(|entry| serde_json::json!({
+            "account": account.as_str(), "revision": boundary, "timestamp": entry.timestamp_ms, "key": id(&entry.key)
+        }).to_string())
+        };
+        let mut coverage = self.coverage.clone();
+        coverage.unresolved_candidates = self.candidates.len();
+        Ok(MentionsPage {
+            entries,
+            next_cursor,
+            end_reached,
+            coverage,
+            unread_count: self.entries.values().filter(|entry| !entry.read).count(),
+            revision: self.revision,
+            boundary: MentionsBoundary {
+                account: account.clone(),
+                revision: boundary,
+            },
+        })
+    }
+
+    pub fn context(
+        &self,
+        key: &MentionKey,
+    ) -> Result<(SavedMentionContext, Vec<MediaRegistration>), Error> {
+        let entry = self
+            .entries
+            .get(&id(key))
+            .ok_or_else(|| Error::new(ErrorKind::EventNotFound, "mention was not found"))?;
+        let mut media = Vec::new();
+        let mut item = |key: &String| {
+            self.events.get(key).map(|event| {
+                media.extend(event.media.clone());
+                event.item.clone()
+            })
+        };
+        let context = self.windows.get(&id(key)).map(|window| EventContext {
+            events_before: window.before.iter().filter_map(&mut item).collect(),
+            event: window.target.as_ref().and_then(&mut item),
+            events_after: window.after.iter().filter_map(&mut item).collect(),
+            start_token: window.start.clone(),
+            end_token: window.end.clone(),
+        });
+        Ok((
+            SavedMentionContext {
+                key: key.clone(),
+                state: entry.capture.clone(),
+                context,
+                revision: self.revision,
+            },
+            media,
+        ))
+    }
+
+    pub fn collect_events(&mut self) {
+        let mut used: BTreeSet<String> = self.entries.keys().cloned().collect();
+        for window in self.windows.values() {
+            used.extend(window.before.iter().chain(&window.after).cloned());
+            used.extend(window.target.iter().cloned());
+        }
+        self.events.retain(|key, _| used.contains(key));
+        self.capture_attempts
+            .retain(|key, _| self.entries.contains_key(key));
+    }
+
+    pub fn evict_one(&mut self) -> bool {
+        let oldest = |keys: Vec<String>, entries: &BTreeMap<String, MentionEntry>| {
+            keys.into_iter()
+                .min_by_key(|key| entries.get(key).map_or(0, |entry| entry.timestamp_ms))
+        };
+        if let Some(key) = oldest(
+            self.windows
+                .keys()
+                .filter(|key| self.entries.get(*key).is_some_and(|entry| entry.read))
+                .cloned()
+                .collect(),
+            &self.entries,
+        )
+        .or_else(|| oldest(self.windows.keys().cloned().collect(), &self.entries))
+        {
+            self.windows.remove(&key);
+            if let Some(entry) = self.entries.get_mut(&key) {
+                entry.capture = MentionCaptureState::Unavailable;
+                entry.revision = self.revision;
+            }
+        } else if let Some(key) = self
+            .entries
+            .iter()
+            .min_by_key(|(_, entry)| (!entry.read, entry.timestamp_ms))
+            .map(|(key, _)| key.clone())
+        {
+            self.entries.remove(&key);
+        } else if let Some(key) = self.candidates.keys().next().cloned() {
+            self.candidates.remove(&key);
+        } else if let Some(key) = self.edits.keys().next().cloned() {
+            self.edits.remove(&key);
+        } else if let Some(key) = self.redacted.keys().next().cloned() {
+            self.redacted.remove(&key);
+        } else {
+            return false;
+        }
+        self.coverage.truncated = true;
+        self.collect_events();
+        true
+    }
+
+    pub fn bound(&mut self, entries: usize, events: usize, candidates: usize) {
+        while self.entries.len() > entries {
+            if let Some(key) = self
+                .entries
+                .iter()
+                .min_by_key(|(_, entry)| (!entry.read, entry.timestamp_ms))
+                .map(|(key, _)| key.clone())
+            {
+                self.entries.remove(&key);
+                self.windows.remove(&key);
+                self.coverage.truncated = true;
+            }
+        }
+        self.collect_events();
+        while self.events.len() > events && self.evict_one() {}
+        while self.candidates.len() > candidates {
+            let key = self.candidates.keys().next().cloned().unwrap();
+            self.candidates.remove(&key);
+            self.coverage.truncated = true;
+        }
+        for map in [&mut self.redacted] {
+            while map.len() > entries + candidates {
+                let key = map
+                    .iter()
+                    .min_by_key(|(_, timestamp)| *timestamp)
+                    .map(|(key, _)| key.clone())
+                    .unwrap();
+                map.remove(&key);
+                self.coverage.truncated = true;
+            }
+        }
+        while self.edits.len() > candidates {
+            let key = self.edits.keys().next().cloned().unwrap();
+            self.edits.remove(&key);
+            self.coverage.truncated = true;
+        }
+        self.coverage.unresolved_candidates = self.candidates.len();
+    }
+}

Added file: src/mentions/state_tests.rs+458 additions@@ -0,0 +1,458 @@
+use ruma::{event_id, user_id};
+
+use super::state::{Data, SavedEvent, Window, id};
+use crate::{
+    MentionCaptureState, MentionEntry, MentionKey, MentionReason, Message, MessageKind, SendState,
+    Sender, TimelineContent, TimelineEvent, TimelineItem, TimelineItemId,
+};
+
+fn key(room: &str, event: &str) -> MentionKey {
+    MentionKey {
+        room_id: format!("!{room}:mentions.example").parse().unwrap(),
+        event_id: format!("${event}:mentions.example").parse().unwrap(),
+    }
+}
+
+fn entry(key: MentionKey, timestamp_ms: u64, discovery_revision: u64, read: bool) -> MentionEntry {
+    MentionEntry {
+        key,
+        timestamp_ms,
+        discovered_at_ms: timestamp_ms,
+        discovery_revision,
+        revision: discovery_revision,
+        event: TimelineItem::DayDivider { timestamp_ms },
+        reasons: vec![MentionReason::Direct],
+        read,
+        capture: MentionCaptureState::Ready,
+        room_name: None,
+        notification_suppressed: false,
+    }
+}
+
+fn message_event(event_id: &str, timestamp_ms: u64, body: &str) -> TimelineItem {
+    let event_id: ruma::OwnedEventId = event_id.parse().unwrap();
+    TimelineItem::Event(Box::new(TimelineEvent {
+        item_id: TimelineItemId::new(format!("item-{event_id}")),
+        event_id: Some(event_id),
+        transaction_id: None,
+        sender: Sender {
+            user_id: user_id!("@bob:mentions.example").to_owned(),
+            display_name: Some("Bob".to_owned()),
+            avatar: None,
+            name_ambiguous: false,
+        },
+        timestamp_ms,
+        own: false,
+        send_state: SendState::Sent,
+        content: TimelineContent::Message(Message {
+            kind: MessageKind::Text,
+            body: body.to_owned(),
+            geo_uri: None,
+            formatted_body: None,
+            mentions: None,
+            edited: false,
+            media: None,
+            link_previews: Vec::new(),
+        }),
+        reply_to: None,
+        thread_root: None,
+        thread_summary: None,
+        reactions: Vec::new(),
+        read_by: Vec::new(),
+        editable: false,
+    }))
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn pagination_keeps_its_discovery_boundary_and_stable_ties() {
+    let account = user_id!("@alice:mentions.example").to_owned();
+    let ordered = vec![
+        key("room", "latest"),
+        key("room", "tie-z"),
+        key("room", "tie-b"),
+        key("room", "tie-a"),
+        key("room", "oldest"),
+    ];
+    let mut data = Data {
+        revision: 1,
+        ..Data::default()
+    };
+    for (mention, timestamp) in [
+        (ordered[0].clone(), 300),
+        (ordered[1].clone(), 200),
+        (ordered[2].clone(), 200),
+        (ordered[3].clone(), 200),
+        (ordered[4].clone(), 100),
+    ] {
+        data.entries
+            .insert(id(&mention), entry(mention, timestamp, 1, false));
+    }
+
+    let first = data.page(&account, None, 2).unwrap();
+    assert_eq!(
+        first
+            .entries
+            .iter()
+            .map(|entry| entry.key.clone())
+            .collect::<Vec<_>>(),
+        ordered[..2].to_vec()
+    );
+    let mut cursor = first.next_cursor.unwrap();
+
+    data.revision = 2;
+    let later = key("room", "discovered-later");
+    data.entries.insert(id(&later), entry(later, 50, 2, false));
+
+    let mut paged = first
+        .entries
+        .into_iter()
+        .map(|entry| entry.key)
+        .collect::<Vec<_>>();
+    loop {
+        let page = data.page(&account, Some(&cursor), 2).unwrap();
+        paged.extend(page.entries.into_iter().map(|entry| entry.key));
+        match page.next_cursor {
+            Some(next) => cursor = next,
+            None => break,
+        }
+    }
+    assert_eq!(paged, ordered);
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn pagination_rejects_a_forged_account_and_a_future_revision() {
+    let account = user_id!("@alice:mentions.example").to_owned();
+    let mut data = Data {
+        revision: 1,
+        ..Data::default()
+    };
+    for event in ["one", "two"] {
+        let mention = key("room", event);
+        data.entries
+            .insert(id(&mention), entry(mention, 10, 1, false));
+    }
+    let cursor = data.page(&account, None, 1).unwrap().next_cursor.unwrap();
+
+    let mut forged_account: serde_json::Value = serde_json::from_str(&cursor).unwrap();
+    forged_account["account"] = serde_json::Value::String("@mallory:mentions.example".to_owned());
+    assert!(
+        data.page(&account, Some(&forged_account.to_string()), 1)
+            .is_err()
+    );
+
+    let mut future_revision: serde_json::Value = serde_json::from_str(&cursor).unwrap();
+    future_revision["revision"] = serde_json::json!(data.revision + 1);
+    assert!(
+        data.page(&account, Some(&future_revision.to_string()), 1)
+            .is_err()
+    );
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn retention_discards_read_context_first_and_keeps_shared_events_until_unused() {
+    let read_key = key("room", "read-mention");
+    let unread_key = key("room", "unread-mention");
+    let shared_key = key("room", "shared-context");
+    let read_id = id(&read_key);
+    let unread_id = id(&unread_key);
+    let shared_id = id(&shared_key);
+    let mut data = Data {
+        revision: 3,
+        ..Data::default()
+    };
+    data.entries
+        .insert(read_id.clone(), entry(read_key, 10, 1, true));
+    data.entries
+        .insert(unread_id.clone(), entry(unread_key, 20, 2, false));
+    data.events.insert(
+        shared_id.clone(),
+        SavedEvent {
+            item: message_event("$shared-context:mentions.example", 15, "shared"),
+            media: Vec::new(),
+            raw: None,
+        },
+    );
+    data.windows.insert(
+        read_id.clone(),
+        Window {
+            before: vec![shared_id.clone()],
+            target: None,
+            after: Vec::new(),
+            start: None,
+            end: None,
+        },
+    );
+    data.windows.insert(
+        unread_id.clone(),
+        Window {
+            before: vec![shared_id.clone()],
+            target: None,
+            after: Vec::new(),
+            start: None,
+            end: None,
+        },
+    );
+
+    assert!(data.evict_one());
+    assert!(!data.windows.contains_key(&read_id));
+    assert!(data.windows.contains_key(&unread_id));
+    assert_eq!(
+        data.entries[&read_id].capture,
+        MentionCaptureState::Unavailable
+    );
+    assert!(!data.entries[&unread_id].read);
+    assert!(data.events.contains_key(&shared_id));
+
+    assert!(data.evict_one());
+    assert!(data.windows.is_empty());
+    assert!(data.entries.contains_key(&read_id));
+    assert!(data.entries.contains_key(&unread_id));
+    assert!(!data.events.contains_key(&shared_id));
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn context_uses_the_redacted_saved_event_instead_of_the_entry_preview() {
+    let mention = key("room", "redacted-target");
+    let mention_id = id(&mention);
+    let original = message_event(
+        "$redacted-target:mentions.example",
+        42,
+        "private original body",
+    );
+    let mut redacted = original.clone();
+    if let TimelineItem::Event(event) = &mut redacted {
+        event.content = TimelineContent::Redacted;
+        event.reply_to = None;
+        event.reactions.clear();
+    }
+    let mut data = Data::default();
+    data.entries.insert(
+        mention_id.clone(),
+        MentionEntry {
+            event: original,
+            ..entry(mention.clone(), 42, 1, false)
+        },
+    );
+    data.events.insert(
+        mention_id.clone(),
+        SavedEvent {
+            item: redacted,
+            media: Vec::new(),
+            raw: None,
+        },
+    );
+    data.windows.insert(
+        mention_id,
+        Window {
+            before: Vec::new(),
+            target: Some(id(&mention)),
+            after: Vec::new(),
+            start: Some("start".to_owned()),
+            end: Some("end".to_owned()),
+        },
+    );
+
+    let (context, media) = data.context(&mention).unwrap();
+    let saved = context.context.unwrap().event.unwrap();
+    let TimelineItem::Event(saved) = saved else {
+        panic!("the saved target should remain a timeline event");
+    };
+    assert_eq!(saved.content, TimelineContent::Redacted);
+    assert_eq!(
+        saved.event_id.as_deref(),
+        Some(event_id!("$redacted-target:mentions.example"))
+    );
+    assert!(media.is_empty());
+}
+
+#[cfg(any(feature = "sqlite", feature = "indexeddb"))]
+mod persistence {
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    use ruma::{events::room::MediaSource, user_id};
+    use serde_json::json;
+
+    use super::*;
+    use crate::{
+        MediaId, MediaKind, StoreConfig,
+        mentions::store::{Account, MentionsStore, Write},
+        normalise::{MediaRegistration, MediaSourceInfo},
+    };
+
+    static STORES: AtomicUsize = AtomicUsize::new(0);
+    const MAX_BYTES: usize = 64 * 1024 * 1024;
+
+    fn account() -> Account {
+        Account {
+            homeserver: "https://mentions.example/".to_owned(),
+            user_id: user_id!("@alice:mentions.example").to_owned(),
+        }
+    }
+
+    fn config() -> StoreConfig {
+        let number = STORES.fetch_add(1, Ordering::Relaxed);
+        #[cfg(feature = "sqlite")]
+        {
+            StoreConfig::sqlite(
+                std::env::temp_dir().join(format!(
+                    "macltok-mentions-state-{}-{number}",
+                    std::process::id()
+                )),
+                "state test passphrase",
+            )
+        }
+        #[cfg(feature = "indexeddb")]
+        {
+            StoreConfig::indexeddb(
+                format!("macltok-mentions-state-{}-{number}", js_sys::Date::now()),
+                "state test passphrase",
+            )
+        }
+    }
+
+    fn media_registration() -> MediaRegistration {
+        MediaRegistration {
+            id: MediaId::new("test-scope#image".to_owned()),
+            kind: MediaKind::Image,
+            full: MediaSourceInfo {
+                source: MediaSource::Plain(
+                    ruma::mxc_uri!("mxc://mentions.example/image").to_owned(),
+                ),
+                mimetype: Some("image/png".to_owned()),
+                declared_size: Some(1234),
+            },
+            thumbnail: None,
+        }
+    }
+
+    fn saved_data() -> Data {
+        let mention = key("persisted-room", "persisted-mention");
+        let mention_id = id(&mention);
+        let context_item =
+            message_event("$persisted-mention:mentions.example", 42, "saved message");
+        let mut data = Data {
+            revision: 1,
+            ..Data::default()
+        };
+        data.entries.insert(
+            mention_id.clone(),
+            MentionEntry {
+                event: context_item.clone(),
+                ..entry(mention.clone(), 42, 1, true)
+            },
+        );
+        data.events.insert(
+            mention_id.clone(),
+            SavedEvent {
+                item: context_item,
+                media: vec![media_registration()],
+                raw: Some(
+                    json!({"event_id": "$persisted-mention:mentions.example", "body": "saved raw"}),
+                ),
+            },
+        );
+        data.windows.insert(
+            mention_id.clone(),
+            Window {
+                before: Vec::new(),
+                target: Some(mention_id),
+                after: Vec::new(),
+                start: Some("start-token".to_owned()),
+                end: Some("end-token".to_owned()),
+            },
+        );
+        data.checkpoints
+            .insert("sync-connection".to_owned(), "position-1".to_owned());
+        data.history_cursor = Some("history-position".to_owned());
+        data
+    }
+
+    async fn open(config: &StoreConfig) -> MentionsStore {
+        MentionsStore::open(config, account(), MAX_BYTES)
+            .await
+            .unwrap()
+    }
+
+    #[cfg_attr(not(target_family = "wasm"), tokio::test)]
+    #[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+    async fn encrypted_store_roundtrips_inbox_context_read_state_and_checkpoints() {
+        let config = config();
+        let data = saved_data();
+        let mut store = open(&config).await;
+        assert_eq!(
+            store
+                .commit(
+                    0,
+                    vec![Write::Set(
+                        "inbox".to_owned(),
+                        serde_json::to_value(&data).unwrap(),
+                    )],
+                )
+                .await
+                .unwrap(),
+            1
+        );
+        drop(store);
+
+        let mut restored = open(&config).await;
+        let mut restored_data: Data = restored.read("inbox").unwrap().unwrap();
+        assert_eq!(restored.revision(), restored_data.revision);
+        assert!(restored_data.entries.values().next().unwrap().read);
+        assert_eq!(
+            restored_data
+                .checkpoints
+                .get("sync-connection")
+                .map(String::as_str),
+            Some("position-1")
+        );
+        let mention = restored_data.entries.values().next().unwrap().key.clone();
+        let (context, media) = restored_data.context(&mention).unwrap();
+        assert_eq!(
+            context.context.unwrap().start_token.as_deref(),
+            Some("start-token")
+        );
+        assert_eq!(media.len(), 1);
+        assert_eq!(media[0].id.as_str(), "test-scope#image");
+        assert_eq!(media[0].full.mimetype.as_deref(), Some("image/png"));
+        let event = restored_data.events.values().next().unwrap();
+        assert_eq!(event.raw.as_ref().unwrap()["body"], "saved raw");
+
+        restored_data.revision = 2;
+        let updated_entry = restored_data.entries.values_mut().next().unwrap();
+        updated_entry.read = false;
+        updated_entry.revision = 2;
+        restored_data
+            .checkpoints
+            .insert("sync-connection".to_owned(), "position-2".to_owned());
+        restored
+            .commit(
+                1,
+                vec![Write::Set(
+                    "inbox".to_owned(),
+                    serde_json::to_value(&restored_data).unwrap(),
+                )],
+            )
+            .await
+            .unwrap();
+        drop(restored);
+
+        let restored = open(&config).await;
+        let restored_data: Data = restored.read("inbox").unwrap().unwrap();
+        assert_eq!(restored.revision(), 2);
+        assert_eq!(restored_data.revision, 2);
+        assert!(!restored_data.entries.values().next().unwrap().read);
+        assert_eq!(
+            restored_data
+                .checkpoints
+                .get("sync-connection")
+                .map(String::as_str),
+            Some("position-2")
+        );
+        drop(restored);
+        config.delete().await.unwrap();
+    }
+}

Added file: src/mentions/store/indexeddb.rs+217 additions@@ -0,0 +1,217 @@
+use std::{collections::BTreeMap, ops::Deref};
+
+use indexed_db_futures::{
+    Build,
+    database::Database,
+    error::{Error as IndexedDbError, OpenDbError},
+    prelude::*,
+    transaction::{Transaction, TransactionDurability, TransactionMode, TransactionOptions},
+    typed_array::{Uint8Array, Uint8ArraySlice},
+};
+
+use super::Snapshot;
+
+const RECORDS: &str = "records";
+const CIPHER: &str = "!cipher";
+const HEAD: &str = "!head";
+const INCOMPLETE_METADATA: &str = "mentions database metadata is incomplete";
+const INVALID_RECORDS: &str = "mentions database records are inconsistent";
+const RESERVED_ROW_KEY: &str = "mentions row key uses a reserved metadata key";
+
+struct DatabaseHandle(Database);
+
+impl Deref for DatabaseHandle {
+    type Target = Database;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl Drop for DatabaseHandle {
+    fn drop(&mut self) {
+        self.0.clone().close();
+    }
+}
+
+pub(super) struct Backend {
+    name: String,
+}
+
+impl Backend {
+    pub(super) async fn open(name: String) -> Result<Self, crate::Error> {
+        let _database = open_database(&name)
+            .await
+            .map_err(|error| super::storage_error("opening the mentions database", error))?;
+        Ok(Self { name })
+    }
+
+    pub(super) async fn load(&self) -> Result<Option<Snapshot>, crate::Error> {
+        let database = open_database(&self.name)
+            .await
+            .map_err(|error| super::storage_error("opening the mentions database", error))?;
+        let snapshot = read_snapshot(&database).await;
+        match snapshot {
+            Ok(snapshot) => Ok(snapshot),
+            Err(ReadError::Invalid(message)) => {
+                Err(crate::Error::new(crate::ErrorKind::Store, message))
+            }
+            Err(ReadError::Storage(error)) => {
+                Err(super::storage_error("reading the mentions database", error))
+            }
+        }
+    }
+
+    pub(super) async fn commit(
+        &self,
+        expected: Option<Vec<u8>>,
+        exported: Vec<u8>,
+        head: Vec<u8>,
+        writes: BTreeMap<String, Option<Vec<u8>>>,
+    ) -> Result<(), crate::Error> {
+        let database = open_database(&self.name)
+            .await
+            .map_err(|error| super::storage_error("opening the mentions database", error))?;
+        let committed = write_snapshot(&database, expected, exported, head, writes).await;
+        match committed {
+            Ok(()) => Ok(()),
+            Err(CommitError::Conflict) => Err(super::conflict()),
+            Err(CommitError::Invalid(message)) => {
+                Err(crate::Error::new(crate::ErrorKind::Store, message))
+            }
+            Err(CommitError::Storage(error)) => {
+                Err(super::storage_error("writing the mentions database", error))
+            }
+        }
+    }
+}
+
+async fn open_database(name: &str) -> Result<DatabaseHandle, OpenDbError> {
+    Database::open(name)
+        .with_version(1u32)
+        .with_on_upgrade_needed(
+            |_, transaction: &Transaction<'_>| -> Result<(), IndexedDbError> {
+                transaction.db().create_object_store(RECORDS).build()?;
+                Ok(())
+            },
+        )
+        .build()?
+        .await
+        .map(DatabaseHandle)
+}
+
+enum ReadError {
+    Invalid(&'static str),
+    Storage(IndexedDbError),
+}
+
+impl From<IndexedDbError> for ReadError {
+    fn from(error: IndexedDbError) -> Self {
+        Self::Storage(error)
+    }
+}
+
+async fn read_snapshot(database: &Database) -> Result<Option<Snapshot>, ReadError> {
+    let transaction = database
+        .transaction(RECORDS)
+        .with_mode(TransactionMode::Readonly)
+        .build()?;
+    let store = transaction.object_store(RECORDS)?;
+    let keys = store.get_all_keys::<String>().build()?;
+    let values = store.get_all::<Uint8Array>().build()?;
+    let keys = keys.await?.collect::<Result<Vec<_>, _>>()?;
+    let values = values.await?.collect::<Result<Vec<_>, _>>()?;
+    if keys.len() != values.len() {
+        return Err(ReadError::Invalid(INVALID_RECORDS));
+    }
+    let mut records = keys
+        .into_iter()
+        .zip(values)
+        .map(|(key, value)| (key, Vec::<u8>::from(value)))
+        .collect::<BTreeMap<_, _>>();
+    if records.is_empty() {
+        return Ok(None);
+    }
+    let exported = records.remove(CIPHER);
+    let head = records.remove(HEAD);
+    match (exported, head) {
+        (Some(exported), Some(head)) => Ok(Some(Snapshot {
+            exported,
+            head,
+            rows: records,
+        })),
+        _ => Err(ReadError::Invalid(INCOMPLETE_METADATA)),
+    }
+}
+
+enum CommitError {
+    Conflict,
+    Invalid(&'static str),
+    Storage(IndexedDbError),
+}
+
+impl From<IndexedDbError> for CommitError {
+    fn from(error: IndexedDbError) -> Self {
+        Self::Storage(error)
+    }
+}
+
+async fn write_snapshot(
+    database: &Database,
+    expected: Option<Vec<u8>>,
+    exported: Vec<u8>,
+    head: Vec<u8>,
+    writes: BTreeMap<String, Option<Vec<u8>>>,
+) -> Result<(), CommitError> {
+    let mut options = TransactionOptions::new();
+    options.set_durability(TransactionDurability::Strict);
+    let transaction = database
+        .transaction(RECORDS)
+        .with_mode(TransactionMode::Readwrite)
+        .with_options(options)
+        .build()?;
+    let current = transaction
+        .object_store(RECORDS)?
+        .get::<Uint8Array, _, _>(HEAD)
+        .await?
+        .map(Vec::<u8>::from);
+    if current != expected {
+        let _ = transaction.abort().await;
+        return Err(CommitError::Conflict);
+    }
+    if writes.keys().any(|key| key == CIPHER || key == HEAD) {
+        let _ = transaction.abort().await;
+        return Err(CommitError::Invalid(RESERVED_ROW_KEY));
+    }
+    let requests = (|| -> Result<(), IndexedDbError> {
+        let store = transaction.object_store(RECORDS)?;
+        store
+            .put(Uint8ArraySlice::new(&exported))
+            .with_key(CIPHER)
+            .build()?;
+        store
+            .put(Uint8ArraySlice::new(&head))
+            .with_key(HEAD)
+            .build()?;
+        for (key, value) in writes {
+            match value {
+                Some(value) => {
+                    store
+                        .put(Uint8ArraySlice::new(&value))
+                        .with_key(key)
+                        .build()?;
+                }
+                None => {
+                    store.delete(key).build()?;
+                }
+            }
+        }
+        Ok(())
+    })();
+    if let Err(error) = requests {
+        let _ = transaction.abort().await;
+        return Err(CommitError::Storage(error));
+    }
+    transaction.commit().await?;
+    Ok(())
+}

Added file: src/mentions/store/mod.rs+336 additions@@ -0,0 +1,336 @@
+use std::{collections::BTreeMap, fmt};
+
+use matrix_sdk::{SendOutsideWasm, SyncOutsideWasm};
+use matrix_sdk_store_encryption::StoreCipher;
+use ruma::OwnedUserId;
+use serde::{Deserialize, Serialize, de::DeserializeOwned};
+use serde_json::Value;
+
+use crate::{Error, ErrorKind, StoreConfig};
+
+#[cfg(feature = "sqlite")]
+mod sqlite;
+#[cfg(feature = "sqlite")]
+use sqlite::Backend;
+#[cfg(feature = "indexeddb")]
+mod indexeddb;
+#[cfg(feature = "indexeddb")]
+use indexeddb::Backend;
+
+const SCHEMA: u32 = 1;
+const MAX_RECORDS: usize = 35_128;
+
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct Account {
+    pub(crate) homeserver: String,
+    pub(crate) user_id: OwnedUserId,
+}
+
+#[derive(Serialize, Deserialize)]
+struct Head {
+    schema: u32,
+    account: Account,
+    revision: u64,
+    records: usize,
+    bytes: usize,
+}
+
+#[derive(Serialize, Deserialize)]
+struct Record {
+    schema: u32,
+    account: Account,
+    key: String,
+    value: Value,
+}
+
+pub(super) struct Snapshot {
+    pub(super) exported: Vec<u8>,
+    pub(super) head: Vec<u8>,
+    pub(super) rows: BTreeMap<String, Vec<u8>>,
+}
+
+pub(crate) enum Write {
+    Set(String, Value),
+    Remove(String),
+}
+
+pub(crate) struct MentionsStore {
+    backend: Backend,
+    cipher: StoreCipher,
+    account: Account,
+    snapshot: Snapshot,
+    revision: u64,
+    max_bytes: usize,
+}
+
+impl fmt::Debug for MentionsStore {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("MentionsStore")
+            .field("revision", &self.revision)
+            .field("records", &self.snapshot.rows.len())
+            .finish_non_exhaustive()
+    }
+}
+
+impl MentionsStore {
+    pub(crate) async fn open(
+        config: &StoreConfig,
+        account: Account,
+        max_bytes: usize,
+    ) -> Result<Self, Error> {
+        let backend = Backend::open(config.mentions_location()).await?;
+        let (cipher, snapshot, revision) = match backend.load().await? {
+            Some(snapshot) => {
+                validate_size(&snapshot, max_bytes)?;
+                let cipher = StoreCipher::import(config.passphrase(), &snapshot.exported)
+                    .map_err(|error| storage_error("opening the mentions cipher", error))?;
+                let head: Head = cipher
+                    .decrypt_value(&snapshot.head)
+                    .map_err(|error| storage_error("opening the mentions header", error))?;
+                validate_account(head.schema, &head.account, &account)?;
+                if head.records != snapshot.rows.len() || head.bytes != row_bytes(&snapshot.rows)? {
+                    return Err(invalid(
+                        "mentions records do not match their committed header",
+                    ));
+                }
+                for (key, encrypted) in &snapshot.rows {
+                    let record: Record = cipher
+                        .decrypt_value(encrypted)
+                        .map_err(|error| storage_error("opening a mentions record", error))?;
+                    validate_account(record.schema, &record.account, &account)?;
+                    if storage_key(&cipher, &record.key) != *key {
+                        return Err(invalid("a mentions record belongs to a different key"));
+                    }
+                }
+                let revision = head.revision;
+                (cipher, snapshot, revision)
+            }
+            None => {
+                let cipher = StoreCipher::new()
+                    .map_err(|error| storage_error("creating the mentions cipher", error))?;
+                let exported = cipher
+                    .export(config.passphrase())
+                    .map_err(|error| storage_error("sealing the mentions cipher", error))?;
+                let head = cipher
+                    .encrypt_value(&Head {
+                        schema: SCHEMA,
+                        account: account.clone(),
+                        revision: 0,
+                        records: 0,
+                        bytes: 0,
+                    })
+                    .map_err(|error| storage_error("sealing the mentions header", error))?;
+                let snapshot = Snapshot {
+                    exported,
+                    head,
+                    rows: BTreeMap::new(),
+                };
+                validate_size(&snapshot, max_bytes)?;
+                backend
+                    .commit(
+                        None,
+                        snapshot.exported.clone(),
+                        snapshot.head.clone(),
+                        BTreeMap::new(),
+                    )
+                    .await?;
+                (cipher, snapshot, 0)
+            }
+        };
+        validate_size(&snapshot, max_bytes)?;
+        Ok(Self {
+            backend,
+            cipher,
+            account,
+            snapshot,
+            revision,
+            max_bytes,
+        })
+    }
+
+    pub(crate) fn revision(&self) -> u64 {
+        self.revision
+    }
+
+    pub(crate) fn read<T: DeserializeOwned>(&self, key: &str) -> Result<Option<T>, Error> {
+        let Some(encrypted) = self.snapshot.rows.get(&storage_key(&self.cipher, key)) else {
+            return Ok(None);
+        };
+        let record: Record = self
+            .cipher
+            .decrypt_value(encrypted)
+            .map_err(|error| storage_error("opening a mentions record", error))?;
+        validate_account(record.schema, &record.account, &self.account)?;
+        if record.key != key {
+            return Err(invalid("a mentions record belongs to a different key"));
+        }
+        serde_json::from_value(record.value)
+            .map(Some)
+            .map_err(|error| storage_error("decoding a mentions record", error))
+    }
+
+    pub(crate) async fn commit(
+        &mut self,
+        expected_revision: u64,
+        writes: Vec<Write>,
+    ) -> Result<u64, Error> {
+        if self.revision != expected_revision {
+            return Err(conflict());
+        }
+        if writes.is_empty() {
+            return Ok(self.revision);
+        }
+        let revision = self
+            .revision
+            .checked_add(1)
+            .ok_or_else(|| invalid("mentions revision exhausted"))?;
+        let mut changes = BTreeMap::new();
+        for write in writes {
+            match write {
+                Write::Set(key, value) => {
+                    let hashed = storage_key(&self.cipher, &key);
+                    let record = Record {
+                        schema: SCHEMA,
+                        account: self.account.clone(),
+                        key,
+                        value,
+                    };
+                    let encrypted = self
+                        .cipher
+                        .encrypt_value(&record)
+                        .map_err(|error| storage_error("sealing a mentions record", error))?;
+                    changes.insert(hashed, Some(encrypted));
+                }
+                Write::Remove(key) => {
+                    changes.insert(storage_key(&self.cipher, &key), None);
+                }
+            }
+        }
+        let mut records = self.snapshot.rows.len();
+        let mut bytes = row_bytes(&self.snapshot.rows)?;
+        for (key, value) in &changes {
+            if let Some(previous) = self.snapshot.rows.get(key) {
+                bytes -= key.len() + previous.len();
+                records -= 1;
+            }
+            if let Some(value) = value {
+                bytes = bytes
+                    .checked_add(key.len())
+                    .and_then(|bytes| bytes.checked_add(value.len()))
+                    .ok_or_else(|| invalid("mentions byte count overflow"))?;
+                records += 1;
+            }
+        }
+        let head = self
+            .cipher
+            .encrypt_value(&Head {
+                schema: SCHEMA,
+                account: self.account.clone(),
+                revision,
+                records,
+                bytes,
+            })
+            .map_err(|error| storage_error("sealing the mentions header", error))?;
+        validate_budget(
+            bytes,
+            records,
+            self.snapshot.exported.len(),
+            head.len(),
+            self.max_bytes,
+        )?;
+        self.backend
+            .commit(
+                Some(self.snapshot.head.clone()),
+                self.snapshot.exported.clone(),
+                head.clone(),
+                changes.clone(),
+            )
+            .await?;
+        for (key, value) in changes {
+            match value {
+                Some(value) => {
+                    self.snapshot.rows.insert(key, value);
+                }
+                None => {
+                    self.snapshot.rows.remove(&key);
+                }
+            }
+        }
+        self.snapshot.head = head;
+        self.revision = revision;
+        Ok(revision)
+    }
+}
+
+fn validate_account(schema: u32, actual: &Account, expected: &Account) -> Result<(), Error> {
+    if schema != SCHEMA {
+        return Err(invalid("unsupported mentions schema"));
+    }
+    if actual != expected {
+        return Err(invalid("mentions store belongs to a different account"));
+    }
+    Ok(())
+}
+
+fn validate_size(snapshot: &Snapshot, max_bytes: usize) -> Result<(), Error> {
+    validate_budget(
+        row_bytes(&snapshot.rows)?,
+        snapshot.rows.len(),
+        snapshot.exported.len(),
+        snapshot.head.len(),
+        max_bytes,
+    )
+}
+
+fn validate_budget(
+    row_bytes: usize,
+    records: usize,
+    exported_len: usize,
+    head_len: usize,
+    max_bytes: usize,
+) -> Result<(), Error> {
+    let bytes = row_bytes
+        .checked_add(exported_len)
+        .and_then(|bytes| bytes.checked_add(head_len))
+        .ok_or_else(|| invalid("mentions byte count overflow"))?;
+    if bytes > max_bytes || records > MAX_RECORDS {
+        return Err(invalid("mentions storage limit exceeded"));
+    }
+    Ok(())
+}
+
+fn row_bytes(rows: &BTreeMap<String, Vec<u8>>) -> Result<usize, Error> {
+    rows.iter().try_fold(0usize, |bytes, (key, value)| {
+        bytes
+            .checked_add(key.len())
+            .and_then(|bytes| bytes.checked_add(value.len()))
+            .ok_or_else(|| invalid("mentions byte count overflow"))
+    })
+}
+
+fn storage_key(cipher: &StoreCipher, key: &str) -> String {
+    cipher
+        .hash_key("macltok-mentions", key.as_bytes())
+        .iter()
+        .map(|byte| format!("{byte:02x}"))
+        .collect()
+}
+
+fn invalid(message: &'static str) -> Error {
+    Error::new(ErrorKind::Store, message)
+}
+
+pub(super) fn conflict() -> Error {
+    invalid("mentions store changed, reopen before retrying")
+}
+
+pub(super) fn storage_error(
+    context: &'static str,
+    source: impl std::error::Error + SendOutsideWasm + SyncOutsideWasm + 'static,
+) -> Error {
+    Error::with_source(ErrorKind::Store, context, source)
+}
+
+#[cfg(test)]
+mod tests;

Added file: src/mentions/store/sqlite.rs+214 additions@@ -0,0 +1,214 @@
+use std::{
+    collections::BTreeMap,
+    fs::{self, OpenOptions},
+    io,
+    path::{Path, PathBuf},
+    time::Duration,
+};
+
+use rusqlite::{Connection, OptionalExtension, TransactionBehavior, params};
+
+use super::{Snapshot, conflict, storage_error};
+use crate::{Error, ErrorKind};
+
+const CIPHER_KEY: &str = "!cipher";
+const HEAD_KEY: &str = "!head";
+
+pub(super) struct Backend {
+    path: PathBuf,
+}
+
+impl Backend {
+    pub(super) async fn open(path: PathBuf) -> Result<Self, Error> {
+        let setup_path = path.clone();
+        tokio::task::spawn_blocking(move || initialize(&setup_path))
+            .await
+            .map_err(|error| storage_error("opening the mentions store", error))??;
+        Ok(Self { path })
+    }
+
+    pub(super) async fn load(&self) -> Result<Option<Snapshot>, Error> {
+        let path = self.path.clone();
+        tokio::task::spawn_blocking(move || load_snapshot(&path))
+            .await
+            .map_err(|error| storage_error("loading the mentions store", error))?
+    }
+
+    pub(super) async fn commit(
+        &self,
+        expected: Option<Vec<u8>>,
+        exported: Vec<u8>,
+        head: Vec<u8>,
+        writes: BTreeMap<String, Option<Vec<u8>>>,
+    ) -> Result<(), Error> {
+        let path = self.path.clone();
+        tokio::task::spawn_blocking(move || {
+            commit_snapshot(&path, expected, exported, head, writes)
+        })
+        .await
+        .map_err(|error| storage_error("committing the mentions store", error))?
+    }
+}
+
+fn initialize(path: &Path) -> Result<(), Error> {
+    let parent = path
+        .parent()
+        .filter(|parent| !parent.as_os_str().is_empty())
+        .unwrap_or_else(|| Path::new("."));
+    fs::create_dir_all(parent)
+        .map_err(|error| storage_error("creating the mentions store directory", error))?;
+    create_private_file(path)
+        .map_err(|error| storage_error("creating the mentions database file", error))?;
+    let connection = connect(path)?;
+    connection
+        .execute(
+            "CREATE TABLE IF NOT EXISTS records (key TEXT PRIMARY KEY, value BLOB NOT NULL)",
+            [],
+        )
+        .map_err(|error| storage_error("initializing the mentions database", error))?;
+    Ok(())
+}
+
+fn connect(path: &Path) -> Result<Connection, Error> {
+    let connection = Connection::open(path)
+        .map_err(|error| storage_error("opening the mentions database", error))?;
+    connection
+        .busy_timeout(Duration::from_secs(5))
+        .map_err(|error| storage_error("configuring the mentions database", error))?;
+    connection
+        .execute_batch("PRAGMA synchronous = FULL")
+        .map_err(|error| storage_error("configuring the mentions database", error))?;
+    Ok(connection)
+}
+
+fn load_snapshot(path: &Path) -> Result<Option<Snapshot>, Error> {
+    let mut connection = connect(path)?;
+    let transaction = connection
+        .transaction_with_behavior(TransactionBehavior::Deferred)
+        .map_err(|error| storage_error("starting a mentions snapshot", error))?;
+    let mut rows = BTreeMap::new();
+    {
+        let mut statement = transaction
+            .prepare("SELECT key, value FROM records")
+            .map_err(|error| storage_error("reading the mentions snapshot", error))?;
+        let result = statement
+            .query_map([], |row| {
+                Ok((row.get::<_, String>(0)?, row.get::<_, Vec<u8>>(1)?))
+            })
+            .map_err(|error| storage_error("reading the mentions snapshot", error))?;
+        for row in result {
+            let (key, value) =
+                row.map_err(|error| storage_error("reading the mentions snapshot", error))?;
+            rows.insert(key, value);
+        }
+    }
+    transaction
+        .commit()
+        .map_err(|error| storage_error("finishing the mentions snapshot", error))?;
+    if rows.is_empty() {
+        return Ok(None);
+    }
+    let exported = rows.remove(CIPHER_KEY).ok_or_else(|| {
+        Error::new(
+            ErrorKind::Store,
+            "mentions store is missing cipher metadata",
+        )
+    })?;
+    let head = rows
+        .remove(HEAD_KEY)
+        .ok_or_else(|| Error::new(ErrorKind::Store, "mentions store is missing head metadata"))?;
+    Ok(Some(Snapshot {
+        exported,
+        head,
+        rows,
+    }))
+}
+
+fn commit_snapshot(
+    path: &Path,
+    expected: Option<Vec<u8>>,
+    exported: Vec<u8>,
+    head: Vec<u8>,
+    writes: BTreeMap<String, Option<Vec<u8>>>,
+) -> Result<(), Error> {
+    let mut connection = connect(path)?;
+    let transaction = connection
+        .transaction_with_behavior(TransactionBehavior::Immediate)
+        .map_err(|error| storage_error("starting a mentions commit", error))?;
+    let current: Option<Vec<u8>> = transaction
+        .query_row(
+            "SELECT value FROM records WHERE key = ?1",
+            [HEAD_KEY],
+            |row| row.get(0),
+        )
+        .optional()
+        .map_err(|error| storage_error("checking the mentions store head", error))?;
+    if current != expected {
+        return Err(conflict());
+    }
+    if writes.contains_key(CIPHER_KEY) || writes.contains_key(HEAD_KEY) {
+        return Err(Error::new(
+            ErrorKind::Store,
+            "mentions record uses a reserved key",
+        ));
+    }
+    transaction
+        .execute(
+            "INSERT INTO records (key, value) VALUES (?1, ?2) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+            params![CIPHER_KEY, exported],
+        )
+        .map_err(|error| storage_error("writing mentions cipher metadata", error))?;
+    transaction
+        .execute(
+            "INSERT INTO records (key, value) VALUES (?1, ?2) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+            params![HEAD_KEY, head],
+        )
+        .map_err(|error| storage_error("writing the mentions store head", error))?;
+    for (key, value) in writes {
+        match value {
+            Some(value) => {
+                transaction
+                    .execute(
+                        "INSERT INTO records (key, value) VALUES (?1, ?2) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+                        params![key, value],
+                    )
+                    .map_err(|error| storage_error("writing a mentions record", error))?;
+            }
+            None => {
+                transaction
+                    .execute("DELETE FROM records WHERE key = ?1", [key])
+                    .map_err(|error| storage_error("deleting a mentions record", error))?;
+            }
+        }
+    }
+    transaction
+        .commit()
+        .map_err(|error| storage_error("finishing a mentions commit", error))
+}
+
+#[cfg(unix)]
+fn create_private_file(path: &Path) -> io::Result<()> {
+    use std::os::unix::fs::OpenOptionsExt;
+
+    match OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .mode(0o600)
+        .open(path)
+    {
+        Ok(file) => drop(file),
+        Err(error) if error.kind() == io::ErrorKind::AlreadyExists => {}
+        Err(error) => return Err(error),
+    }
+    Ok(())
+}
+
+#[cfg(not(unix))]
+fn create_private_file(path: &Path) -> io::Result<()> {
+    match OpenOptions::new().write(true).create_new(true).open(path) {
+        Ok(file) => drop(file),
+        Err(error) if error.kind() == io::ErrorKind::AlreadyExists => {}
+        Err(error) => return Err(error),
+    }
+    Ok(())
+}

Added file: src/mentions/store/tests.rs+418 additions@@ -0,0 +1,418 @@
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+use ruma::user_id;
+use serde_json::{Value, json};
+
+use super::{Account, Head, MentionsStore, Write, row_bytes, storage_key};
+use crate::StoreConfig;
+
+#[cfg(target_family = "wasm")]
+wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser);
+
+static STORES: AtomicUsize = AtomicUsize::new(0);
+const MAX_BYTES: usize = 64 * 1024 * 1024;
+
+fn account() -> Account {
+    Account {
+        homeserver: "https://mentions.example/".to_owned(),
+        user_id: user_id!("@alice:mentions.example").to_owned(),
+    }
+}
+
+fn config() -> StoreConfig {
+    let number = STORES.fetch_add(1, Ordering::Relaxed);
+    #[cfg(feature = "sqlite")]
+    return StoreConfig::sqlite(
+        std::env::temp_dir().join(format!("macltok-mentions-{}-{number}", std::process::id())),
+        "test store passphrase",
+    );
+    #[cfg(feature = "indexeddb")]
+    return StoreConfig::indexeddb(
+        format!("macltok-mentions-{}-{number}", js_sys::Date::now()),
+        "test store passphrase",
+    );
+}
+
+fn set(key: &str, value: Value) -> Write {
+    Write::Set(key.to_owned(), value)
+}
+
+async fn open(config: &StoreConfig) -> MentionsStore {
+    MentionsStore::open(config, account(), MAX_BYTES)
+        .await
+        .unwrap()
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn entries_context_read_state_and_checkpoint_restore_together() {
+    let config = config();
+    let mut store = open(&config).await;
+    assert_eq!(store.revision(), 0);
+    assert_eq!(
+        store
+            .commit(
+                0,
+                vec![
+                    set(
+                        "entry/room/event",
+                        json!({"preview": "secret mention preview"})
+                    ),
+                    set("context/room/event", json!({"body": "secret context body"})),
+                    set("read/room/event", json!(false)),
+                    set("checkpoint/sync", json!("position-1")),
+                ]
+            )
+            .await
+            .unwrap(),
+        1
+    );
+    drop(store);
+    let mut restored = open(&config).await;
+    assert_eq!(restored.revision(), 1);
+    assert_eq!(
+        restored.read::<Value>("entry/room/event").unwrap(),
+        Some(json!({"preview": "secret mention preview"}))
+    );
+    assert_eq!(
+        restored.read::<Value>("context/room/event").unwrap(),
+        Some(json!({"body": "secret context body"}))
+    );
+    assert_eq!(
+        restored.read::<bool>("read/room/event").unwrap(),
+        Some(false)
+    );
+    assert_eq!(
+        restored
+            .read::<String>("checkpoint/sync")
+            .unwrap()
+            .as_deref(),
+        Some("position-1")
+    );
+    restored
+        .commit(
+            1,
+            vec![
+                Write::Remove("entry/room/event".to_owned()),
+                set("read/room/event", json!(true)),
+                set("checkpoint/sync", json!("position-2")),
+            ],
+        )
+        .await
+        .unwrap();
+    drop(restored);
+    let restored = open(&config).await;
+    assert_eq!(restored.revision(), 2);
+    assert!(
+        restored
+            .read::<Value>("entry/room/event")
+            .unwrap()
+            .is_none()
+    );
+    assert_eq!(
+        restored.read::<bool>("read/room/event").unwrap(),
+        Some(true)
+    );
+    assert_eq!(
+        restored
+            .read::<String>("checkpoint/sync")
+            .unwrap()
+            .as_deref(),
+        Some("position-2")
+    );
+    drop(restored);
+    config.delete().await.unwrap();
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn stale_writers_cannot_overwrite_a_committed_checkpoint() {
+    let config = config();
+    let mut first = open(&config).await;
+    let mut stale = open(&config).await;
+    first
+        .commit(0, vec![set("checkpoint", json!("committed"))])
+        .await
+        .unwrap();
+    assert!(
+        stale
+            .commit(
+                0,
+                vec![
+                    set("checkpoint", json!("stale")),
+                    set("entry", json!("uncommitted")),
+                ]
+            )
+            .await
+            .is_err()
+    );
+    assert_eq!(stale.revision(), 0);
+    assert!(stale.read::<Value>("entry").unwrap().is_none());
+    assert!(
+        first
+            .commit(0, vec![set("checkpoint", json!("wrong revision"))])
+            .await
+            .is_err()
+    );
+    let restored = open(&config).await;
+    assert_eq!(restored.revision(), 1);
+    assert_eq!(
+        restored.read::<String>("checkpoint").unwrap().as_deref(),
+        Some("committed")
+    );
+    assert!(restored.read::<Value>("entry").unwrap().is_none());
+    drop((first, stale, restored));
+    config.delete().await.unwrap();
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn capacity_failure_keeps_the_old_revision_and_checkpoint() {
+    let config = config();
+    let mut store = MentionsStore::open(&config, account(), 4096).await.unwrap();
+    store
+        .commit(0, vec![set("checkpoint", json!("old"))])
+        .await
+        .unwrap();
+    assert!(
+        store
+            .commit(
+                1,
+                vec![
+                    set("checkpoint", json!("new")),
+                    set("entry", json!("x".repeat(16384))),
+                ]
+            )
+            .await
+            .is_err()
+    );
+    assert_eq!(store.revision(), 1);
+    assert_eq!(
+        store.read::<String>("checkpoint").unwrap().as_deref(),
+        Some("old")
+    );
+    assert!(store.read::<Value>("entry").unwrap().is_none());
+    drop(store);
+    let restored = open(&config).await;
+    assert_eq!(restored.revision(), 1);
+    assert_eq!(
+        restored.read::<String>("checkpoint").unwrap().as_deref(),
+        Some("old")
+    );
+    drop(restored);
+    config.delete().await.unwrap();
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn records_hide_content_keys_and_account_metadata() {
+    let config = config();
+    let mut store = open(&config).await;
+    store
+        .commit(
+            0,
+            vec![set(
+                "private/room/event",
+                json!({"body": "a secret saved message"}),
+            )],
+        )
+        .await
+        .unwrap();
+    let snapshot = store.backend.load().await.unwrap().unwrap();
+    let mut bytes = snapshot.exported;
+    bytes.extend(snapshot.head);
+    for (key, value) in snapshot.rows {
+        bytes.extend(key.as_bytes());
+        bytes.extend(value);
+    }
+    #[cfg(feature = "sqlite")]
+    bytes.extend(std::fs::read(config.mentions_location()).unwrap());
+    for secret in [
+        "private/room/event",
+        "a secret saved message",
+        "mentions.example",
+    ] {
+        assert!(
+            !bytes
+                .windows(secret.len())
+                .any(|window| window == secret.as_bytes())
+        );
+    }
+    drop(store);
+    config.delete().await.unwrap();
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn wrong_account_server_and_passphrase_cannot_open_the_store() {
+    let config = config();
+    let store = open(&config).await;
+    drop(store);
+    let other = Account {
+        user_id: user_id!("@bob:mentions.example").to_owned(),
+        ..account()
+    };
+    assert!(
+        MentionsStore::open(&config, other, MAX_BYTES)
+            .await
+            .is_err()
+    );
+    let other_server = Account {
+        homeserver: "https://different.example/".to_owned(),
+        ..account()
+    };
+    assert!(
+        MentionsStore::open(&config, other_server, MAX_BYTES)
+            .await
+            .is_err()
+    );
+    #[cfg(feature = "sqlite")]
+    let wrong_passphrase =
+        StoreConfig::sqlite(config.mentions_location().parent().unwrap(), "incorrect");
+    #[cfg(feature = "indexeddb")]
+    let wrong_passphrase = StoreConfig::indexeddb(config.indexeddb_name(), "incorrect");
+    assert!(
+        MentionsStore::open(&wrong_passphrase, account(), MAX_BYTES)
+            .await
+            .is_err()
+    );
+    drop(open(&config).await);
+    config.delete().await.unwrap();
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn ciphertext_corruption_and_record_swaps_are_rejected() {
+    let config = config();
+    let mut store = open(&config).await;
+    store
+        .commit(
+            0,
+            vec![set("one", json!("first")), set("two", json!("other"))],
+        )
+        .await
+        .unwrap();
+    let one = storage_key(&store.cipher, "one");
+    let two = storage_key(&store.cipher, "two");
+    let mut swapped = store.snapshot.rows.clone();
+    let first = swapped[&one].clone();
+    swapped.insert(one.clone(), swapped[&two].clone());
+    swapped.insert(two, first);
+    let swapped = swapped
+        .into_iter()
+        .map(|(key, value)| (key, Some(value)))
+        .collect();
+    store
+        .backend
+        .commit(
+            Some(store.snapshot.head.clone()),
+            store.snapshot.exported.clone(),
+            store.snapshot.head.clone(),
+            swapped,
+        )
+        .await
+        .unwrap();
+    assert!(
+        MentionsStore::open(&config, account(), MAX_BYTES)
+            .await
+            .is_err()
+    );
+    let mut corrupt = store.snapshot.rows[&one].clone();
+    let middle = corrupt.len() / 2;
+    corrupt[middle] ^= 1;
+    let mut restored = store.snapshot.rows.clone();
+    restored.insert(one, corrupt);
+    let restored = restored
+        .into_iter()
+        .map(|(key, value)| (key, Some(value)))
+        .collect();
+    store
+        .backend
+        .commit(
+            Some(store.snapshot.head.clone()),
+            store.snapshot.exported.clone(),
+            store.snapshot.head.clone(),
+            restored,
+        )
+        .await
+        .unwrap();
+    assert!(
+        MentionsStore::open(&config, account(), MAX_BYTES)
+            .await
+            .is_err()
+    );
+    drop(store);
+    config.delete().await.unwrap();
+}
+
+#[cfg_attr(not(target_family = "wasm"), tokio::test)]
+#[cfg_attr(target_family = "wasm", wasm_bindgen_test::wasm_bindgen_test)]
+async fn unsupported_schema_fails_without_resetting_data() {
+    let config = config();
+    let mut store = open(&config).await;
+    store
+        .commit(0, vec![set("checkpoint", json!("retained"))])
+        .await
+        .unwrap();
+    let header = store
+        .cipher
+        .encrypt_value(&Head {
+            schema: 2,
+            account: account(),
+            revision: 1,
+            records: store.snapshot.rows.len(),
+            bytes: row_bytes(&store.snapshot.rows).unwrap(),
+        })
+        .unwrap();
+    store
+        .backend
+        .commit(
+            Some(store.snapshot.head.clone()),
+            store.snapshot.exported.clone(),
+            header.clone(),
+            Default::default(),
+        )
+        .await
+        .unwrap();
+    assert!(
+        MentionsStore::open(&config, account(), MAX_BYTES)
+            .await
+            .is_err()
+    );
+    assert_eq!(store.backend.load().await.unwrap().unwrap().head, header);
+    drop(store);
+    config.delete().await.unwrap();
+}
+
+#[cfg(feature = "sqlite")]
+#[tokio::test]
+async fn sql_failure_rolls_back_records_and_header_together() {
+    let config = config();
+    let mut store = open(&config).await;
+    let path = config.mentions_location();
+    tokio::task::spawn_blocking(move || {
+        rusqlite::Connection::open(path).unwrap().execute_batch(
+            "CREATE TRIGGER reject_record BEFORE INSERT ON records WHEN NEW.key NOT LIKE '!%' BEGIN SELECT RAISE(ABORT, 'injected write failure'); END;"
+        ).unwrap();
+    }).await.unwrap();
+    assert!(
+        store
+            .commit(
+                0,
+                vec![
+                    set("entry", json!("pending")),
+                    set("checkpoint", json!("new"))
+                ]
+            )
+            .await
+            .is_err()
+    );
+    assert_eq!(store.revision(), 0);
+    drop(store);
+    let restored = open(&config).await;
+    assert_eq!(restored.revision(), 0);
+    assert!(restored.read::<Value>("entry").unwrap().is_none());
+    assert!(restored.read::<Value>("checkpoint").unwrap().is_none());
+    drop(restored);
+    config.delete().await.unwrap();
+}

Added file: src/mentions_model.rs+127 additions@@ -0,0 +1,127 @@
+use ruma::{OwnedEventId, OwnedRoomId, OwnedUserId};
+#[cfg(feature = "serde")]
+use serde::{Deserialize, Serialize};
+
+use crate::{EventContext, TimelineItem};
+
+#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct MentionKey {
+    pub room_id: OwnedRoomId,
+    pub event_id: OwnedEventId,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub enum MentionReason {
+    Direct,
+    Reply,
+    Room,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub enum MentionCaptureState {
+    Pending,
+    Partial,
+    Ready,
+    Unavailable,
+    Failed { message: String, retry_at_ms: u64 },
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct MentionEntry {
+    pub key: MentionKey,
+    pub timestamp_ms: u64,
+    pub discovered_at_ms: u64,
+    pub discovery_revision: u64,
+    pub revision: u64,
+    pub event: TimelineItem,
+    pub reasons: Vec<MentionReason>,
+    pub read: bool,
+    pub capture: MentionCaptureState,
+    pub room_name: Option<String>,
+    pub notification_suppressed: bool,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct MentionCoverage {
+    pub earliest_timestamp_ms: Option<u64>,
+    pub historical_supported: Option<bool>,
+    pub recovering: bool,
+    pub incomplete_history: bool,
+    pub gaps: Vec<MentionGap>,
+    pub truncated: bool,
+    pub unresolved_candidates: usize,
+}
+
+impl Default for MentionCoverage {
+    fn default() -> Self {
+        Self {
+            earliest_timestamp_ms: None,
+            historical_supported: None,
+            recovering: false,
+            incomplete_history: true,
+            gaps: Vec::new(),
+            truncated: false,
+            unresolved_candidates: 0,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct MentionGap {
+    pub room_id: Option<OwnedRoomId>,
+    pub reason: String,
+    pub token: Option<String>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct MentionsBoundary {
+    pub account: OwnedUserId,
+    pub revision: u64,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct MentionsPage {
+    pub entries: Vec<MentionEntry>,
+    pub next_cursor: Option<String>,
+    pub end_reached: bool,
+    pub coverage: MentionCoverage,
+    pub unread_count: usize,
+    pub revision: u64,
+    pub boundary: MentionsBoundary,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct SavedMentionContext {
+    pub key: MentionKey,
+    pub state: MentionCaptureState,
+    pub context: Option<EventContext>,
+    pub revision: u64,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct MentionsUpdate {
+    pub snapshot: MentionsPage,
+    pub upserts: Vec<MentionEntry>,
+    pub removed: Vec<MentionKey>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub enum MentionsCommand {
+    Page { cursor: Option<String>, limit: u16 },
+    Context(MentionKey),
+    RetryContext(MentionKey),
+    SetRead { keys: Vec<MentionKey>, read: bool },
+    ReadThrough(MentionsBoundary),
+    Recover,
+}

Modified file: src/mirror.rs+24 additions@@ -45,6 +45,7 @@ pub struct State {
     pub encryption: Option<EncryptionState>,
     pub verification: Option<VerificationState>,
     pub verification_target: Option<VerificationTarget>,
+    pub mentions: Option<crate::MentionsPage>,
     pub rooms: Vector<RoomSummary>,
     pub image_packs: ImagePacks,
     pub timelines: imbl::HashMap<TimelineId, TimelineState>,
@@ -121,6 +122,7 @@ pub enum StateChange {
     Encryption(EncryptionState),
     Verification(VerificationState),
     VerificationTarget(VerificationTarget),
+    Mentions(crate::MentionsUpdate),
     /// room modes arrive with the `Rooms` that follows
     NotificationSettings,
     Rooms(Vector<RoomSummary>),
@@ -200,6 +202,7 @@ impl Mirror {
             encryption: handle.encryption_state(),
             verification: None,
             verification_target: None,
+            mentions: None,
             rooms: Vector::new(),
             image_packs: ImagePacks::default(),
             timelines: imbl::HashMap::new(),
@@ -262,6 +265,7 @@ impl Mirror {
                 Some(StateChange::SessionSaved)
             }),
             Event::SessionAccessRejected { soft_logout } => self.publish(|state| {
+                state.mentions = None;
                 state.session = match soft_logout {
                     Some(device_id) => SessionStatus::SoftLoggedOut { device_id },
                     None => SessionStatus::AccessRevoked,
@@ -269,6 +273,7 @@ impl Mirror {
                 Some(StateChange::Session(state.session.clone()))
             }),
             Event::LoggedOut => self.publish(|state| {
+                state.mentions = None;
                 state.session = SessionStatus::LoggedOut;
                 Some(StateChange::Session(SessionStatus::LoggedOut))
             }),
@@ -290,6 +295,25 @@ impl Mirror {
                 self.publish(|_| Some(StateChange::NotificationSettings));
             }
             Event::RoomsChanged => self.refetch_rooms(),
+            Event::MentionsChanged(update) => self.publish(|state| {
+                if state.session != SessionStatus::Active
+                    || state
+                        .user_id
+                        .as_ref()
+                        .is_some_and(|account| account != &update.snapshot.boundary.account)
+                {
+                    return None;
+                }
+                if state
+                    .mentions
+                    .as_ref()
+                    .map_or(false, |current| update.snapshot.revision < current.revision)
+                {
+                    return None;
+                }
+                state.mentions = Some(update.snapshot.clone());
+                Some(StateChange::Mentions(update))
+            }),
             Event::ImagePacksChanged => self.refetch_image_packs(),
             Event::EncryptionChanged(encryption) => self.publish(|state| {
                 state.encryption = Some(encryption.clone());

Modified file: src/model.rs+4 additions@@ -24,6 +24,7 @@ pub enum Command {
     Room(RoomCommand),
     Timeline(TimelineCommand),
     EventContext(EventContextCommand),
+    Mentions(crate::MentionsCommand),
     Media(MediaCommand),
     Encryption(EncryptionCommand),
     Notification(NotificationCommand),
@@ -665,6 +666,8 @@ pub enum CommandOutput {
     },
     EventContext(EventContext),
     EventContextPage(EventContextPage),
+    MentionsPage(crate::MentionsPage),
+    MentionContext(crate::SavedMentionContext),
 }
 
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -885,6 +888,7 @@ pub enum Event {
     NotificationSettingsChanged,
     VerificationTargetChanged(VerificationTarget),
     RoomsChanged,
+    MentionsChanged(crate::MentionsUpdate),
     /// an image pack came, went or changed somewhere. ask `image_packs` again
     ImagePacksChanged,
     /// replaces whatever you had for this timeline. every diff after it applies to it

Modified file: src/normalise/media.rs+7 additions−2 deletions@@ -44,6 +44,7 @@ impl MediaScope {
 }
 
 #[derive(Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub(crate) struct MediaRegistration {
     pub(crate) id: MediaId,
     pub(crate) kind: MediaKind,
@@ -52,6 +53,7 @@ pub(crate) struct MediaRegistration {
 }
 
 #[derive(Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub(crate) struct MediaSourceInfo {
     pub(crate) source: MediaSource,
     pub(crate) mimetype: Option<String>,
@@ -208,7 +210,7 @@ pub(super) fn media_id(identity: &str, suffix: &str) -> MediaId {
     MediaId::new(format!("{identity}#{suffix}"))
 }
 
-fn media_sticker_registration(
+pub(super) fn media_sticker_registration(
     identity: &str,
     content: &StickerEventContent,
 ) -> Option<MediaRegistration> {
@@ -227,7 +229,10 @@ fn media_sticker_registration(
     })
 }
 
-fn media_registration(identity: &str, message: &MessageType) -> Option<MediaRegistration> {
+pub(super) fn media_registration(
+    identity: &str,
+    message: &MessageType,
+) -> Option<MediaRegistration> {
     match message {
         MessageType::Image(content) => media_registration_with_info(
             identity,

Modified file: src/normalise/mod.rs+2 additions@@ -2,6 +2,7 @@ mod image_pack;
 mod link_preview;
 mod media;
 mod member;
+mod observed;
 mod room;
 mod timeline;
 
@@ -11,6 +12,7 @@ pub(crate) use image_pack::{
 pub(crate) use link_preview::{ROOM_PREVIEW_URLS, server_preview, url_previews_allowed};
 pub(crate) use media::{MediaRegistration, MediaScope, MediaSourceInfo};
 pub(crate) use member::member_summary;
+pub(crate) use observed::normalise_observed;
 pub(crate) use room::notification_mode;
 pub(crate) use room::{room_summaries, space_child, stored_space_order};
 pub(crate) use timeline::{message_kind, normalise_timeline, normalise_timeline_diffs};

Added file: src/normalise/observed.rs+270 additions@@ -0,0 +1,270 @@
+use ruma::{
+    OwnedEventId, UserId,
+    events::{
+        poll::{start::PollStartEventContent, unstable_start::UnstablePollStartEventContent},
+        room::message::{
+            MessageType, Relation, RoomMessageEventContent, RoomMessageEventContentWithoutRelation,
+        },
+        sticker::StickerEventContent,
+    },
+};
+use serde_json::Value;
+
+use super::{
+    link_preview::sender_previews,
+    media::{
+        MediaRegistration, media_descriptor_for_sticker, media_registration,
+        media_sticker_registration,
+    },
+    timeline::formatted_body,
+};
+use crate::{
+    Message, MessageMentions, ReplyDetails, ReplyReference, SendState, Sender, TimelineContent,
+    TimelineEvent, TimelineItem, TimelineItemId, UtdCause,
+};
+
+pub(crate) fn normalise_observed(
+    value: &Value,
+    current_user_id: Option<&UserId>,
+    identity: &str,
+) -> Option<(TimelineItem, Vec<MediaRegistration>)> {
+    let event_id: OwnedEventId = serde_json::from_value(value.get("event_id")?.clone()).ok()?;
+    let sender_id: ruma::OwnedUserId = serde_json::from_value(value.get("sender")?.clone()).ok()?;
+    let timestamp_ms = value.get("origin_server_ts")?.as_u64()?;
+    let event_type = value.get("type")?.as_str()?.to_owned();
+    let own = current_user_id.is_some_and(|user_id| user_id.as_str() == sender_id.as_str());
+    let redacted = value
+        .get("unsigned")
+        .and_then(|unsigned| unsigned.get("redacted_because"))
+        .is_some();
+    let mut media = Vec::new();
+    let (content, reply_to, thread_root) = if redacted {
+        (TimelineContent::Redacted, None, None)
+    } else if event_type == "m.room.message" {
+        match value
+            .get("content")
+            .cloned()
+            .and_then(|content| serde_json::from_value::<RoomMessageEventContent>(content).ok())
+        {
+            Some(mut message) => {
+                let (reply_to, thread_root) = relation_refs(message.relates_to.as_ref());
+                let relation_replacement = match &message.relates_to {
+                    Some(Relation::Replacement(replacement)) => {
+                        Some(replacement.new_content.clone())
+                    }
+                    _ => None,
+                };
+                let bundled_replacement = value
+                    .get("unsigned")
+                    .and_then(|unsigned| unsigned.get("m.relations"))
+                    .and_then(|relations| relations.get("m.replace"))
+                    .and_then(|edit| {
+                        let edit_sender = edit.get("sender")?.as_str()?;
+                        if edit_sender != sender_id.as_str() {
+                            return None;
+                        }
+                        edit.get("content")?.get("m.new_content").cloned()
+                    })
+                    .and_then(|content| {
+                        serde_json::from_value::<RoomMessageEventContentWithoutRelation>(content)
+                            .ok()
+                    });
+                let edited = relation_replacement.is_some()
+                    || bundled_replacement.is_some()
+                    || value
+                        .get("unsigned")
+                        .and_then(|unsigned| unsigned.get("macltok_edited"))
+                        .and_then(Value::as_bool)
+                        .unwrap_or(false);
+                if let Some(replacement) = relation_replacement.or(bundled_replacement) {
+                    message.apply_replacement(replacement);
+                }
+                let message_type = &message.msgtype;
+                media.extend(media_registration(identity, message_type));
+                let previews = sender_previews(Some(identity), message_type);
+                media.extend(
+                    previews
+                        .iter()
+                        .filter_map(|(_, registration)| registration.clone()),
+                );
+                (
+                    TimelineContent::Message(Message {
+                        kind: super::message_kind(message_type),
+                        body: message.body().to_owned(),
+                        geo_uri: match message_type {
+                            MessageType::Location(location) => Some(location.geo_uri.clone()),
+                            _ => None,
+                        },
+                        formatted_body: formatted_body(message_type),
+                        mentions: message.mentions.as_ref().map(|mentions| MessageMentions {
+                            user_ids: mentions.user_ids.iter().cloned().collect(),
+                            room: mentions.room,
+                        }),
+                        edited,
+                        media: super::media::media_from_message(identity, message_type),
+                        link_previews: previews.into_iter().map(|(preview, _)| preview).collect(),
+                    }),
+                    reply_to,
+                    thread_root,
+                )
+            }
+            None => (TimelineContent::Other { event_type }, None, None),
+        }
+    } else if event_type == "m.room.encrypted" {
+        (
+            TimelineContent::UnableToDecrypt(UtdCause::Unknown),
+            None,
+            None,
+        )
+    } else if event_type == "m.sticker" {
+        match value
+            .get("content")
+            .cloned()
+            .and_then(|content| serde_json::from_value::<StickerEventContent>(content).ok())
+        {
+            Some(sticker) => {
+                let (reply_to, thread_root) = relation_refs(sticker.relates_to.as_ref());
+                media.extend(media_sticker_registration(identity, &sticker));
+                (
+                    TimelineContent::Sticker {
+                        body: sticker.body.clone(),
+                        media: media_descriptor_for_sticker(identity, &sticker),
+                    },
+                    reply_to,
+                    thread_root,
+                )
+            }
+            None => (TimelineContent::Other { event_type }, None, None),
+        }
+    } else if event_type == "m.poll.start" || event_type == "org.matrix.msc3381.poll.start" {
+        let poll_content = value.get("content");
+        let question = poll_content.and_then(|content| poll_question(content, &event_type));
+        match question {
+            Some(question) => {
+                let (reply_to, thread_root) =
+                    poll_content.map(raw_relation_refs).unwrap_or_default();
+                (TimelineContent::Poll { question }, reply_to, thread_root)
+            }
+            None => (TimelineContent::Other { event_type }, None, None),
+        }
+    } else if let Some(state_key) = value.get("state_key").and_then(Value::as_str) {
+        (
+            TimelineContent::OtherState {
+                event_type,
+                state_key: state_key.to_owned(),
+            },
+            None,
+            None,
+        )
+    } else {
+        (TimelineContent::Other { event_type }, None, None)
+    };
+    let event = TimelineEvent {
+        item_id: TimelineItemId::new(identity.to_owned()),
+        event_id: Some(event_id),
+        transaction_id: None,
+        sender: Sender {
+            user_id: sender_id,
+            display_name: None,
+            avatar: None,
+            name_ambiguous: false,
+        },
+        timestamp_ms,
+        own,
+        send_state: SendState::Sent,
+        content,
+        reply_to: reply_to.map(|event_id| ReplyReference {
+            event_id,
+            details: ReplyDetails::Pending,
+        }),
+        thread_root,
+        thread_summary: None,
+        reactions: Vec::new(),
+        read_by: Vec::new(),
+        editable: false,
+    };
+    Some((TimelineItem::Event(Box::new(event)), media))
+}
+
+fn relation_refs<C>(
+    relation: Option<&Relation<C>>,
+) -> (Option<OwnedEventId>, Option<OwnedEventId>) {
+    match relation {
+        Some(Relation::Reply(reply)) => (Some(reply.in_reply_to.event_id.clone()), None),
+        Some(Relation::Thread(thread)) => (
+            thread
+                .in_reply_to
+                .as_ref()
+                .map(|reply| reply.event_id.clone()),
+            Some(thread.event_id.clone()),
+        ),
+        _ => (None, None),
+    }
+}
+
+fn raw_relation_refs(content: &Value) -> (Option<OwnedEventId>, Option<OwnedEventId>) {
+    let Some(relation) = content.get("m.relates_to") else {
+        return (None, None);
+    };
+    let reply_to = relation
+        .get("m.in_reply_to")
+        .and_then(|reply| reply.get("event_id"))
+        .and_then(Value::as_str)
+        .and_then(|event_id| event_id.parse().ok());
+    let thread_root = (relation.get("rel_type").and_then(Value::as_str) == Some("m.thread"))
+        .then(|| relation.get("event_id").and_then(Value::as_str))
+        .flatten()
+        .and_then(|event_id| event_id.parse().ok());
+    (reply_to, thread_root)
+}
+
+fn poll_question(content: &Value, event_type: &str) -> Option<String> {
+    let typed_question = match event_type {
+        "m.poll.start" => serde_json::from_value::<PollStartEventContent>(content.clone())
+            .ok()
+            .and_then(|poll| poll.poll.question.text.find_plain().map(str::to_owned)),
+        "org.matrix.msc3381.poll.start" => {
+            serde_json::from_value::<UnstablePollStartEventContent>(content.clone())
+                .ok()
+                .map(|poll| poll.poll_start().question.text.clone())
+        }
+        _ => None,
+    };
+    typed_question
+        .or_else(|| {
+            content
+                .get("m.poll")
+                .and_then(|poll| poll.get("question"))
+                .and_then(|question| question.get("m.text"))
+                .and_then(generic_text)
+        })
+        .or_else(|| {
+            content
+                .get("org.matrix.msc3381.poll.start")
+                .and_then(|poll| poll.get("question"))
+                .and_then(|question| question.get("org.matrix.msc1767.text"))
+                .and_then(generic_text)
+        })
+        .or_else(|| {
+            ["org.matrix.msc1767.text", "m.text", "question", "body"]
+                .iter()
+                .find_map(|key| content.get(*key).and_then(generic_text))
+        })
+}
+
+fn generic_text(value: &Value) -> Option<String> {
+    match value {
+        Value::String(text) => Some(text.clone()),
+        Value::Array(representations) => representations
+            .iter()
+            .find(|representation| {
+                representation.get("mimetype").and_then(Value::as_str) == Some("text/plain")
+            })
+            .or_else(|| representations.first())
+            .and_then(|representation| representation.get("body"))
+            .and_then(Value::as_str)
+            .map(str::to_owned),
+        Value::Object(_) => value.get("body").and_then(Value::as_str).map(str::to_owned),
+        _ => None,
+    }
+}

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

@@ -436,7 +436,7 @@ fn reactions(event: &EventTimelineItem, current_user_id: Option<&UserId>) -> Vec

436436 .collect()

437437 }

438438

439-fn formatted_body(message: &MessageType) -> Option<String> {

439+pub(super) fn formatted_body(message: &MessageType) -> Option<String> {

440440 let formatted = match message {

441441 MessageType::Text(content) => content.formatted.as_ref(),

442442 MessageType::Emote(content) => content.formatted.as_ref(),

Modified file: src/session_store.rs+3 additions−1 deletions@@ -473,11 +473,12 @@ pub(crate) fn delete_sqlite_store(path: &Path) -> std::io::Result<()> {
     use std::{fs, io::ErrorKind};
 
     // matrix-sdk-sqlite 0.18's database names, which it keeps private
-    const DATABASES: [&str; 4] = [
+    const DATABASES: [&str; 5] = [
         "matrix-sdk-state.sqlite3",
         "matrix-sdk-crypto.sqlite3",
         "matrix-sdk-event-cache.sqlite3",
         "matrix-sdk-media.sqlite3",
+        "macltok-mentions.sqlite3",
     ];
     for database in DATABASES {
         for suffix in ["", "-wal", "-shm", "-journal"] {
@@ -507,6 +508,7 @@ pub(crate) async fn delete_indexeddb_store(name: &str) -> Result<(), DeleteError
         "::matrix-sdk-crypto-meta",
         "::event_cache",
         "::media",
+        "::macltok-mentions",
     ] {
         delete_database(&format!("{name}{suffix}")).await?;
     }

Modified file: src/transport.rs+77 additions−8 deletions@@ -29,14 +29,15 @@ use tokio::sync::{OnceCell, mpsc, oneshot, watch};
 use crate::{
     AccountCommand, AttachmentUpload, Command, CommandOutput, ConnectionState, CreateRoomOptions,
     EncryptionCommand, EncryptionState, Error, ErrorKind, Event, EventContext, EventContextCommand,
-    EventContextPage, EventRef, ImagePackSource,
-    ImagePacks, InteractiveAuth, InteractiveAuthOutcome, LifecycleCommand, LinkPreview, Media,
-    MediaCommand, MediaId, MediaLocation, MediaSize, MemberFilter, MemberSummary, MessageContent,
-    MessageEditContent, NotificationCommand, OwnDevice, PackCommand, PackImageInfo, PackUsage,
-    Patch, PowerLevelChanges, Profile, PushNotification, PushNotificationEvent,
-    PushNotificationStatus, RoomCommand, RoomListFilter, RoomNotificationMode,
-    RoomNotificationSettings, RoomPowerLevels, RoomSummary, SpaceChild, TimelineCommand,
-    TimelineId, VerificationAction, VerificationTarget,
+    EventContextPage, EventRef, ImagePackSource, ImagePacks, InteractiveAuth,
+    InteractiveAuthOutcome, LifecycleCommand, LinkPreview, Media, MediaCommand, MediaId,
+    MediaLocation, MediaSize, MemberFilter, MemberSummary, MentionKey, MentionsBoundary,
+    MentionsCommand, MentionsPage, MessageContent, MessageEditContent, NotificationCommand,
+    OwnDevice, PackCommand, PackImageInfo, PackUsage, Patch, PowerLevelChanges, Profile,
+    PushNotification, PushNotificationEvent, PushNotificationStatus, RoomCommand, RoomListFilter,
+    RoomNotificationMode, RoomNotificationSettings, RoomPowerLevels, RoomSummary,
+    SavedMentionContext, SpaceChild, TimelineCommand, TimelineId, VerificationAction,
+    VerificationTarget,
     encryption::encryption_state,
     engine::{MediaService, StoreLock},
     model::{PushNotificationRoom, PushNotificationSender},
@@ -385,6 +386,74 @@ impl ClientHandle {
         }
     }
 
+    pub async fn mentions_page(
+        &self,
+        cursor: Option<String>,
+        limit: u32,
+    ) -> Result<MentionsPage, Error> {
+        match self
+            .execute(Command::Mentions(MentionsCommand::Page {
+                cursor,
+                limit: limit.min(50) as u16,
+            }))
+            .await?
+        {
+            CommandOutput::MentionsPage(page) => Ok(page),
+            output => Err(unexpected("mentions page", &output)),
+        }
+    }
+
+    pub async fn mention_context(
+        &self,
+        room_id: &RoomId,
+        event_id: &EventId,
+    ) -> Result<SavedMentionContext, Error> {
+        self.mention_context_command(MentionsCommand::Context(MentionKey {
+            room_id: room_id.to_owned(),
+            event_id: event_id.to_owned(),
+        }))
+        .await
+    }
+
+    pub async fn retry_mention_context(
+        &self,
+        room_id: &RoomId,
+        event_id: &EventId,
+    ) -> Result<SavedMentionContext, Error> {
+        self.mention_context_command(MentionsCommand::RetryContext(MentionKey {
+            room_id: room_id.to_owned(),
+            event_id: event_id.to_owned(),
+        }))
+        .await
+    }
+
+    async fn mention_context_command(
+        &self,
+        command: MentionsCommand,
+    ) -> Result<SavedMentionContext, Error> {
+        match self.execute(Command::Mentions(command)).await? {
+            CommandOutput::MentionContext(context) => Ok(context),
+            output => Err(unexpected("mention context", &output)),
+        }
+    }
+
+    pub async fn set_mentions_read(&self, keys: Vec<MentionKey>, read: bool) -> Result<(), Error> {
+        self.run(Command::Mentions(MentionsCommand::SetRead { keys, read }))
+            .await
+    }
+
+    pub async fn mark_mentions_read_through(
+        &self,
+        boundary: MentionsBoundary,
+    ) -> Result<(), Error> {
+        self.run(Command::Mentions(MentionsCommand::ReadThrough(boundary)))
+            .await
+    }
+
+    pub async fn recover_mentions(&self) -> Result<(), Error> {
+        self.run(Command::Mentions(MentionsCommand::Recover)).await
+    }
+
     pub async fn send_message(
         &self,
         timeline_id: TimelineId,

Added file: tests/mentions_checkpoint.rs+155 additions@@ -0,0 +1,155 @@
+use std::{sync::Arc, time::Duration};
+
+use matrix_sdk::{
+    Client, Room,
+    ruma::{api::client::sync::sync_events::v5, events::AnySyncTimelineEvent, room_id, serde::Raw},
+    sliding_sync::{SlidingSyncList, SlidingSyncMode},
+    test_utils::mocks::MatrixMockServer,
+};
+use serde_json::{Value, json};
+use tokio::sync::{Notify, Semaphore};
+
+async fn saved_position(client: &Client) -> Option<String> {
+    let machine = client.olm_machine_for_testing().await;
+    let key = format!(
+        "sliding_sync_store::mentions-spike::{}::instance",
+        client.user_id().unwrap()
+    );
+    let saved = machine
+        .as_ref()
+        .unwrap()
+        .store()
+        .get_custom_value(&key)
+        .await
+        .unwrap()?;
+    serde_json::from_slice::<Value>(&saved).unwrap()["pos"]
+        .as_str()
+        .map(ToOwned::to_owned)
+}
+
+async fn server_with_mention() -> (MatrixMockServer, Client) {
+    let server = MatrixMockServer::new().await;
+    let client = server.client_builder().build().await;
+    let mut response = v5::Response::new("position-1".to_owned());
+    response.rooms.insert(
+        room_id!("!checkpoint:localhost").to_owned(),
+        serde_json::from_value(json!({
+                "initial": true,
+                "required_state": [],
+                "timeline": [{
+                    "type": "m.room.message",
+                    "event_id": "$checkpoint-mention",
+                    "sender": "@sender:localhost",
+                    "origin_server_ts": 1,
+                    "content": {
+                        "msgtype": "m.text",
+                        "body": "checkpoint candidate",
+                        "m.mentions": { "user_ids": [client.user_id().unwrap()] }
+                    }
+                }]
+        }))
+        .unwrap(),
+    );
+    server.mock_sliding_sync().ok(response).mount().await;
+    (server, client)
+}
+
+async fn new_sync(client: &Client) -> matrix_sdk::sliding_sync::SlidingSync {
+    client
+        .sliding_sync("mentions-spike")
+        .unwrap()
+        .share_pos()
+        .add_list(
+            SlidingSyncList::builder("mentions")
+                .sync_mode(SlidingSyncMode::new_selective().add_range(0..=0)),
+        )
+        .build()
+        .await
+        .unwrap()
+}
+
+#[tokio::test]
+async fn awaited_event_handler_fences_position_even_after_caller_cancellation() {
+    let (server, client) = server_with_mention().await;
+
+    let entered = Arc::new(Notify::new());
+    let committed = Arc::new(Semaphore::new(0));
+    let handler = client.add_event_handler({
+        let entered = entered.clone();
+        let committed = committed.clone();
+        move |event: Raw<AnySyncTimelineEvent>, room: Room| {
+            let entered = entered.clone();
+            let committed = committed.clone();
+            async move {
+                assert_eq!(room.room_id().as_str(), "!checkpoint:localhost");
+                assert_eq!(
+                    event.get_field::<String>("event_id").unwrap().as_deref(),
+                    Some("$checkpoint-mention")
+                );
+                entered.notify_one();
+                committed.acquire().await.unwrap().forget();
+            }
+        }
+    });
+    let sync = new_sync(&client).await;
+    let processing = tokio::spawn(async move { sync.sync_once().await });
+    tokio::time::timeout(Duration::from_secs(5), entered.notified())
+        .await
+        .unwrap();
+    assert!(!processing.is_finished());
+    assert!(saved_position(&client).await.is_none());
+    processing.abort();
+    assert!(processing.await.unwrap_err().is_cancelled());
+    assert!(saved_position(&client).await.is_none());
+
+    committed.add_permits(1);
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while saved_position(&client).await.as_deref() != Some("position-1") {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .unwrap();
+    client.remove_event_handler(handler);
+
+    let restored = new_sync(&client).await;
+    tokio::time::timeout(Duration::from_secs(5), restored.sync_once())
+        .await
+        .unwrap()
+        .unwrap();
+    let requests: Vec<_> = server
+        .received_requests()
+        .await
+        .unwrap()
+        .into_iter()
+        .filter_map(|request| {
+            let body = serde_json::from_slice::<Value>(&request.body).ok()?;
+            let pos = request
+                .url
+                .query_pairs()
+                .find(|(key, _)| key == "pos")
+                .map(|(_, value)| value.into_owned());
+            Some((body, pos))
+        })
+        .filter(|(body, _)| body["conn_id"] == "mentions-spike")
+        .collect();
+    assert_eq!(requests.len(), 2);
+    assert!(requests[0].1.is_none());
+    assert_eq!(requests[1].1.as_deref(), Some("position-1"));
+}
+
+#[tokio::test]
+async fn event_handler_error_does_not_prevent_position_persistence() {
+    let (_server, client) = server_with_mention().await;
+    let handler =
+        client.add_event_handler(|_event: Raw<AnySyncTimelineEvent>, _room: Room| async {
+            Err::<(), _>("the candidate transaction failed")
+        });
+    let sync = new_sync(&client).await;
+    tokio::time::timeout(Duration::from_secs(5), sync.sync_once())
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(saved_position(&client).await.as_deref(), Some("position-1"));
+    client.remove_event_handler(handler);
+}

Added file: tests/mentions_decryption.rs+128 additions@@ -0,0 +1,128 @@
+use std::time::Duration;
+
+use futures_util::StreamExt;
+use matrix_sdk::{
+    deserialized_responses::TimelineEventKind, event_cache::RedecryptorReport,
+    test_utils::mocks::MatrixMockServer,
+};
+use matrix_sdk_test::{JoinedRoomBuilder, event_factory::EventFactory};
+use ruma::{RoomVersionId, device_id, event_id, room_id, user_id};
+use serde_json::json;
+
+#[tokio::test]
+async fn late_key_exposes_a_mention_without_a_ui_timeline() {
+    let server = MatrixMockServer::new().await;
+    server.mock_crypto_endpoints_preset().await;
+    let alice_id = user_id!("@alice:localhost");
+    let bob_id = user_id!("@bob:localhost");
+    let room_id = room_id!("!mentions-encrypted:localhost");
+    let event_id = event_id!("$late-mention");
+    let alice = server
+        .client_builder_for_crypto_end_to_end(alice_id, device_id!("ALICEDEVICE"))
+        .build()
+        .await;
+    let bob = server
+        .client_builder_for_crypto_end_to_end(bob_id, device_id!("BOBDEVICE"))
+        .build()
+        .await;
+    bob.event_cache().subscribe().unwrap();
+    server.exchange_e2ee_identities(&alice, &bob).await;
+
+    let factory = EventFactory::new().room(room_id).sender(alice_id);
+    let joined = JoinedRoomBuilder::new(room_id)
+        .add_state_event(factory.create(alice_id, RoomVersionId::V1))
+        .add_state_event(factory.room_encryption())
+        .add_state_event(factory.member(alice_id))
+        .add_state_event(factory.member(bob_id));
+    server.sync_room(&alice, joined.clone()).await;
+    server.sync_room(&bob, joined).await;
+
+    let room = alice.get_room(room_id).unwrap();
+    let (encrypted_event, send) = server.mock_room_send().ok_with_capture(event_id, alice_id);
+    let _send = send.mock_once().mount_as_scoped().await;
+    let (_keys, room_key) = server.mock_capture_put_to_device(alice_id).await;
+    server
+        .mock_get_members()
+        .ok(vec![
+            factory.member(alice_id).into_raw(),
+            factory.member(bob_id).into_raw(),
+        ])
+        .mock_once()
+        .mount()
+        .await;
+    room.send_raw(
+        "m.room.message",
+        json!({
+            "msgtype": "m.text",
+            "body": "a private mention",
+            "m.mentions": { "user_ids": [bob_id] }
+        }),
+    )
+    .await
+    .unwrap();
+    let encrypted_event = encrypted_event.await.unwrap();
+    let room_key = room_key.await;
+
+    let mut sync_updates = bob.subscribe_to_all_room_updates();
+    let mut cache_updates = bob.event_cache().subscribe_to_room_generic_updates();
+    let mut reports = bob.event_cache().subscribe_to_decryption_reports();
+    server
+        .sync_room(
+            &bob,
+            JoinedRoomBuilder::new(room_id).add_timeline_event(encrypted_event),
+        )
+        .await;
+    let update = sync_updates.recv().await.unwrap();
+    let event = &update.joined[room_id].timeline.events[0];
+    assert!(matches!(
+        event.kind,
+        TimelineEventKind::UnableToDecrypt { .. }
+    ));
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while cache_updates.recv().await.unwrap().room_id != room_id {}
+    })
+    .await
+    .unwrap();
+
+    server
+        .mock_sync()
+        .ok_and_run(&bob, |sync| {
+            sync.add_to_device_event(room_key.deserialize_as().unwrap());
+        })
+        .await;
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while let Some(report) = reports.next().await {
+            if let Ok(RedecryptorReport::ResolvedUtds {
+                room_id: resolved,
+                events,
+            }) = report
+            {
+                if resolved == room_id && events.contains(event_id) {
+                    return;
+                }
+            }
+        }
+        panic!("decryption reports ended before the mention was decrypted");
+    })
+    .await
+    .unwrap();
+
+    let room = bob.get_room(room_id).unwrap();
+    let (cache, _cache_handles) = room.event_cache().await.unwrap();
+    let decrypted = cache.find_event(event_id).await.unwrap().unwrap();
+    assert!(matches!(decrypted.kind, TimelineEventKind::Decrypted(_)));
+    let content = decrypted
+        .raw()
+        .get_field::<serde_json::Value>("content")
+        .unwrap()
+        .unwrap();
+    assert_eq!(content["body"], "a private mention");
+    assert_eq!(content["m.mentions"]["user_ids"], json!([bob_id]));
+    let push_actions = room
+        .event_push_actions(decrypted.raw())
+        .await
+        .unwrap()
+        .unwrap();
+    assert!(push_actions.iter().any(|action| action.should_notify()));
+    assert_eq!(cache.events().await.unwrap().len(), 1);
+}

Added file: tests/mentions_discovery.rs+232 additions@@ -0,0 +1,232 @@
+use matrix_sdk::{
+    Room,
+    ruma::{
+        UInt,
+        api::client::push::get_notifications::v3,
+        event_id,
+        events::{AnySyncTimelineEvent, Mentions},
+        owned_user_id,
+        push::{Action, EventMatchConditionData, NewConditionalPushRule, PushCondition, Ruleset},
+        room_id,
+        serde::Raw,
+    },
+    test_utils::mocks::MatrixMockServer,
+};
+use matrix_sdk_test::{JoinedRoomBuilder, event_factory::EventFactory};
+use serde_json::json;
+use std::time::Duration;
+use wiremock::{
+    Mock, ResponseTemplate,
+    matchers::{method, path, query_param},
+};
+
+fn explicit_mention(
+    room_id: &matrix_sdk::ruma::RoomId,
+    event_id: &matrix_sdk::ruma::EventId,
+    sender: &matrix_sdk::ruma::UserId,
+    mentioned: &matrix_sdk::ruma::UserId,
+) -> Raw<AnySyncTimelineEvent> {
+    EventFactory::new()
+        .room(room_id)
+        .text_msg("hello")
+        .mentions(Mentions::with_user_ids([mentioned.to_owned()]))
+        .event_id(event_id)
+        .sender(sender)
+        .into_raw_sync()
+}
+
+fn assert_mention_actions(actions: &[Action]) {
+    assert!(
+        actions
+            .iter()
+            .any(|action| matches!(action, Action::Notify))
+    );
+    assert!(actions.iter().any(Action::is_highlight));
+}
+
+async fn sync_room_with_mention(
+    server: &MatrixMockServer,
+    client: &matrix_sdk::Client,
+    room_id: &matrix_sdk::ruma::RoomId,
+    event_id: &matrix_sdk::ruma::EventId,
+) {
+    let user_id = client.user_id().unwrap();
+    let factory = EventFactory::new().room(room_id);
+    let sender = owned_user_id!("@alice:localhost");
+    let event = explicit_mention(room_id, event_id, &sender, user_id);
+    let rules = Ruleset::server_default(user_id);
+
+    server
+        .mock_sync()
+        .ok_and_run(client, |builder| {
+            builder.add_global_account_data(factory.push_rules(rules));
+            builder.add_joined_room(
+                JoinedRoomBuilder::new(room_id)
+                    .add_state_event(factory.member(user_id))
+                    .add_timeline_event(event),
+            );
+        })
+        .await;
+}
+
+async fn actions_for(room: &Room, event: &Raw<AnySyncTimelineEvent>) -> Option<Vec<Action>> {
+    room.event_push_actions(event).await.unwrap()
+}
+
+#[tokio::test]
+async fn joined_room_update_exposes_mention_actions_without_opening_a_ui_timeline() {
+    let server = MatrixMockServer::new().await;
+    let client = server.client_builder().build().await;
+    let room_id = room_id!("!mentions:localhost");
+    let event_id = event_id!("$mention:localhost");
+    let mut updates = client.subscribe_to_all_room_updates();
+
+    sync_room_with_mention(&server, &client, room_id, event_id).await;
+
+    let room_updates = tokio::time::timeout(Duration::from_secs(2), updates.recv())
+        .await
+        .unwrap()
+        .unwrap();
+    let joined = room_updates
+        .joined
+        .get(room_id)
+        .expect("the joined room update was absent");
+    let event = joined
+        .timeline
+        .events
+        .iter()
+        .find(|event| event.event_id().as_deref().map(|id| id.as_str()) == Some(event_id.as_str()))
+        .expect("the explicit mention was absent from the room update");
+    let event_json: serde_json::Value =
+        serde_json::from_str(event.kind.raw().json().get()).unwrap();
+
+    assert_eq!(
+        event_json["content"]["m.mentions"]["user_ids"],
+        json!([client.user_id().unwrap().as_str()])
+    );
+    assert_mention_actions(
+        event
+            .push_actions()
+            .expect("push actions were not computed"),
+    );
+}
+
+#[tokio::test]
+async fn event_cache_generic_update_finds_the_mention_without_opening_a_ui_timeline() {
+    let server = MatrixMockServer::new().await;
+    let client = server.client_builder().build().await;
+    let room_id = room_id!("!cached-mentions:localhost");
+    let event_id = event_id!("$cached-mention:localhost");
+    client.event_cache().subscribe().unwrap();
+    let mut updates = client.event_cache().subscribe_to_room_generic_updates();
+
+    sync_room_with_mention(&server, &client, room_id, event_id).await;
+
+    let update = tokio::time::timeout(Duration::from_secs(2), updates.recv())
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(update.room_id, room_id);
+    let room = client.get_room(room_id).unwrap();
+    let (event_cache, _drop_handles) = room.event_cache().await.unwrap();
+    let event = event_cache.find_event(event_id).await.unwrap().unwrap();
+    assert_eq!(
+        event.event_id().as_deref().map(|id| id.as_str()),
+        Some(event_id.as_str())
+    );
+    assert_mention_actions(
+        event
+            .push_actions()
+            .expect("cached push actions were absent"),
+    );
+}
+
+#[tokio::test]
+async fn ignored_sender_and_muted_room_actions_remain_sdk_push_rule_results() {
+    let server = MatrixMockServer::new().await;
+    let client = server.client_builder().build().await;
+    let ignored_room_id = room_id!("!ignored-sender:localhost");
+    let muted_room_id = room_id!("!muted-room:localhost");
+    let ignored_sender = owned_user_id!("@ignored:localhost");
+    let own_user = client.user_id().unwrap();
+    let factory = EventFactory::new();
+    let ignored_event_id = event_id!("$ignored-mention:localhost");
+    let muted_event_id = event_id!("$muted-message:localhost");
+    let ignored_event =
+        explicit_mention(ignored_room_id, ignored_event_id, &ignored_sender, own_user);
+    let sender = owned_user_id!("@alice:localhost");
+    let muted_event = explicit_mention(muted_room_id, muted_event_id, &sender, own_user);
+    let mut rules = Ruleset::server_default(own_user);
+    rules.override_.shift_insert(
+        1,
+        NewConditionalPushRule::new(
+            "mute-room".to_owned(),
+            vec![PushCondition::EventMatch(EventMatchConditionData::new(
+                "room_id".to_owned(),
+                muted_room_id.to_string(),
+            ))],
+            Vec::new(),
+        )
+        .into(),
+    );
+
+    server
+        .mock_sync()
+        .ok_and_run(&client, |builder| {
+            builder.add_global_account_data(factory.ignored_user_list([ignored_sender.clone()]));
+            builder.add_global_account_data(factory.push_rules(rules));
+            builder.add_joined_room(
+                JoinedRoomBuilder::new(ignored_room_id)
+                    .add_state_event(EventFactory::new().room(ignored_room_id).member(own_user))
+                    .add_timeline_event(ignored_event.clone()),
+            );
+            builder.add_joined_room(
+                JoinedRoomBuilder::new(muted_room_id)
+                    .add_state_event(EventFactory::new().room(muted_room_id).member(own_user))
+                    .add_timeline_event(muted_event.clone()),
+            );
+        })
+        .await;
+
+    assert!(client.is_user_ignored(&ignored_sender).await);
+    let ignored_room = client.get_room(ignored_room_id).unwrap();
+    let ignored_actions = actions_for(&ignored_room, &ignored_event)
+        .await
+        .expect("the ignored sender's push actions could not be computed");
+    assert_mention_actions(&ignored_actions);
+
+    let muted_room = client.get_room(muted_room_id).unwrap();
+    let muted_actions = actions_for(&muted_room, &muted_event)
+        .await
+        .expect("the muted room's push actions could not be computed");
+    assert!(muted_actions.is_empty());
+}
+
+#[tokio::test]
+async fn notifications_v3_request_round_trips_opaque_pagination() {
+    let server = MatrixMockServer::new().await;
+    let client = server.client_builder().build().await;
+    let cursor = "opaque / cursor?x=1&y=2";
+    let next_cursor = "next / cursor?x=3&y=4";
+
+    Mock::given(method("GET"))
+        .and(path("/_matrix/client/v3/notifications"))
+        .and(query_param("from", cursor))
+        .and(query_param("limit", "8"))
+        .and(query_param("only", "highlight"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "next_token": next_cursor,
+            "notifications": [],
+        })))
+        .expect(1)
+        .mount(server.server())
+        .await;
+
+    let mut request = v3::Request::new();
+    request.from = Some(cursor.to_owned());
+    request.limit = Some(UInt::new(8).unwrap());
+    request.only = Some("highlight".to_owned());
+    let response = client.send(request).await.unwrap();
+
+    assert_eq!(response.next_token.as_deref(), Some(next_cursor));
+}

Added file: tests/mentions_inbox.rs+882 additions@@ -0,0 +1,882 @@
+mod support;
+
+use std::{
+    collections::{BTreeMap, HashSet},
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicUsize, Ordering},
+    },
+    time::Duration,
+};
+
+#[cfg(feature = "sqlite")]
+use macltok::{EncryptedSessionStore, PasswordLogin, Restore, Session, SessionStore, StoreConfig};
+use macltok::{Engine, EngineConfig, Event, MentionsPage};
+use matrix_sdk::{
+    Client,
+    ruma::{OwnedRoomId, OwnedUserId, event_id, events::Mentions, room_id, user_id},
+    test_utils::mocks::{MatrixMockServer, RoomContextResponseTemplate},
+};
+use matrix_sdk_test::{ALICE, JoinedRoomBuilder, event_factory::EventFactory};
+use ruma::push::{EventMatchConditionData, NewConditionalPushRule, PushCondition, Ruleset};
+use serde_json::{Value, json};
+#[cfg(feature = "sqlite")]
+use support::receive_until;
+use support::shut_down;
+use wiremock::{
+    Mock, Request, Respond, ResponseTemplate,
+    matchers::{method, path, path_regex, query_param},
+};
+
+#[cfg(feature = "serde")]
+use macltok::{MentionCoverage, MentionsBoundary, MentionsCommand};
+
+const SLIDING_SYNC_PATH: &str = "/_matrix/client/unstable/org.matrix.simplified_msc3575/sync";
+
+struct SlidingFeed {
+    rooms: Arc<Mutex<BTreeMap<OwnedRoomId, Vec<Value>>>>,
+    required_state: Arc<Mutex<BTreeMap<OwnedRoomId, Vec<Value>>>>,
+    requests: Arc<AtomicUsize>,
+}
+
+impl SlidingFeed {
+    fn new(room_id: OwnedRoomId, events: Vec<Value>) -> Self {
+        Self {
+            rooms: Arc::new(Mutex::new(BTreeMap::from([(room_id, events)]))),
+            required_state: Arc::new(Mutex::new(BTreeMap::new())),
+            requests: Arc::new(AtomicUsize::new(0)),
+        }
+    }
+
+    fn replace(&self, room_id: &ruma::RoomId, events: Vec<Value>) {
+        self.rooms
+            .lock()
+            .unwrap()
+            .insert(room_id.to_owned(), events);
+    }
+
+    fn add_room(&self, room_id: &ruma::RoomId, events: Vec<Value>) {
+        self.rooms
+            .lock()
+            .unwrap()
+            .insert(room_id.to_owned(), events);
+    }
+
+    fn set_required_state(&self, room_id: &ruma::RoomId, events: Vec<Value>) {
+        self.required_state
+            .lock()
+            .unwrap()
+            .insert(room_id.to_owned(), events);
+    }
+
+    async fn mount(&self, server: &MatrixMockServer) {
+        Mock::given(method("POST"))
+            .and(path(SLIDING_SYNC_PATH))
+            .respond_with(self.clone())
+            .mount(server.server())
+            .await;
+    }
+}
+
+impl Clone for SlidingFeed {
+    fn clone(&self) -> Self {
+        Self {
+            rooms: self.rooms.clone(),
+            required_state: self.required_state.clone(),
+            requests: self.requests.clone(),
+        }
+    }
+}
+
+impl Respond for SlidingFeed {
+    fn respond(&self, _request: &Request) -> ResponseTemplate {
+        let request = self.requests.fetch_add(1, Ordering::AcqRel);
+        let required_state = self.required_state.lock().unwrap().clone();
+        let rooms: serde_json::Map<String, Value> = self
+            .rooms
+            .lock()
+            .unwrap()
+            .iter()
+            .map(|(room_id, events)| {
+                (
+                    room_id.to_string(),
+                    json!({
+                        "initial": request == 0,
+                        "required_state": required_state
+                            .get(room_id)
+                            .cloned()
+                            .unwrap_or_default(),
+                        "timeline": events,
+                    }),
+                )
+            })
+            .collect();
+        ResponseTemplate::new(200)
+            .set_body_json(json!({
+                "txn_id": null,
+                "pos": format!("mentions-{request}"),
+                "lists": {},
+                "rooms": rooms,
+                "extensions": {},
+            }))
+            .set_delay(Duration::from_millis(20))
+    }
+}
+
+async fn joined_client(server: &MatrixMockServer, room_id: &ruma::RoomId) -> (Client, OwnedUserId) {
+    let client = server.client_builder().build().await;
+    let own_user = client.user_id().unwrap().to_owned();
+    let room_id = room_id.to_owned();
+    server
+        .mock_sync()
+        .ok_and_run(&client, {
+            let own_user = own_user.clone();
+            move |builder| {
+                let factory = EventFactory::new().room(&room_id);
+                builder.add_global_account_data(
+                    factory.push_rules(Ruleset::server_default(&own_user)),
+                );
+                builder.add_joined_room(
+                    JoinedRoomBuilder::new(&room_id).add_state_event(factory.member(&own_user)),
+                );
+            }
+        })
+        .await;
+    (client, own_user)
+}
+
+fn message(
+    event_id: &str,
+    sender: &str,
+    timestamp: u64,
+    body: &str,
+    mentioned: Option<&str>,
+) -> Value {
+    let mut content = json!({ "msgtype": "m.text", "body": body });
+    if let Some(mentioned) = mentioned {
+        content["m.mentions"] = json!({ "user_ids": [mentioned] });
+    }
+    json!({
+        "type": "m.room.message",
+        "event_id": event_id,
+        "sender": sender,
+        "origin_server_ts": timestamp,
+        "content": content,
+    })
+}
+
+fn room_mention(event_id: &str, sender: &str, timestamp: u64) -> Value {
+    let mut event = message(event_id, sender, timestamp, "room mention", None);
+    event["content"]["m.mentions"] = json!({ "room": true });
+    event
+}
+
+async fn mentions_page(
+    events: &mut macltok::EventStream,
+    room_id: &ruma::RoomId,
+    predicate: impl Fn(&MentionsPage) -> bool,
+) -> MentionsPage {
+    mentions_page_with_diagnostics(events, room_id, predicate, None).await
+}
+
+async fn mentions_page_with_diagnostics(
+    events: &mut macltok::EventStream,
+    room_id: &ruma::RoomId,
+    predicate: impl Fn(&MentionsPage) -> bool,
+    diagnostic_server: Option<&MatrixMockServer>,
+) -> MentionsPage {
+    let mut last_page = None;
+    let result = tokio::time::timeout(Duration::from_secs(5), async {
+        while let Some(event) = events.recv().await {
+            match event {
+                Event::TimelineReset { timeline_id, .. } if timeline_id.room_id() == room_id => {
+                    panic!("the unopened room produced a timeline reset");
+                }
+                Event::MentionsChanged(update) => {
+                    let snapshot = update.snapshot;
+                    let matched = predicate(&snapshot);
+                    last_page = Some(snapshot.clone());
+                    if matched {
+                        return snapshot;
+                    }
+                }
+                _ => {}
+            }
+        }
+        panic!("event stream closed before the expected mentions page");
+    })
+    .await;
+
+    match result {
+        Ok(page) => page,
+        Err(_) => {
+            let last_state = last_page.map(|page: MentionsPage| {
+                (
+                    page.revision,
+                    page.unread_count,
+                    page.entries
+                        .iter()
+                        .map(|entry| {
+                            (
+                                entry.key.room_id.to_string(),
+                                entry.key.event_id.to_string(),
+                                entry.capture.clone(),
+                                entry.revision,
+                            )
+                        })
+                        .collect::<Vec<_>>(),
+                )
+            });
+            let requests = if let Some(server) = diagnostic_server {
+                server.server().received_requests().await.map(|requests| {
+                    requests
+                        .iter()
+                        .filter(|request| {
+                            let path = request.url.path();
+                            path.contains(room_id.as_str())
+                                && (path.contains("/context/") || path.ends_with("/messages"))
+                        })
+                        .map(|request| format!("{} {}", request.method, request.url))
+                        .collect::<Vec<_>>()
+                })
+            } else {
+                None
+            };
+            panic!(
+                "expected mentions update did not arrive, last state {last_state:?}, requests {requests:?}"
+            );
+        }
+    }
+}
+
+fn entry_ids(page: &MentionsPage) -> HashSet<String> {
+    page.entries
+        .iter()
+        .map(|entry| entry.key.event_id.to_string())
+        .collect()
+}
+
+async fn wait_for_requests(feed: &SlidingFeed, minimum: usize) {
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while feed.requests.load(Ordering::Acquire) < minimum {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("the sliding sync feed did not receive another request");
+}
+
+async fn mount_messages_page(
+    server: &MatrixMockServer,
+    room_id: &ruma::RoomId,
+    direction: &str,
+    token: &str,
+    limit: u16,
+) {
+    Mock::given(method("GET"))
+        .and(path_regex(format!(
+            r"^/_matrix/client/v3/rooms/{room_id}/messages$"
+        )))
+        .and(query_param("dir", direction))
+        .and(query_param("from", token))
+        .and(move |request: &Request| {
+            request
+                .url
+                .query_pairs()
+                .find(|(key, _)| key == "limit")
+                .map_or(limit == 10, |(_, value)| value == limit.to_string())
+        })
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "start": token,
+            "end": format!("{token}-next"),
+            "chunk": [],
+            "state": [],
+        })))
+        .expect(1)
+        .mount(server.server())
+        .await;
+}
+
+#[tokio::test]
+async fn unopened_room_mentions_are_deduplicated_and_read_through_uses_a_revision_boundary() {
+    let server = MatrixMockServer::new().await;
+    let room_id = room_id!("!mentions-inbox:localhost");
+    let (client, own_user) = joined_client(&server, room_id).await;
+    let sender = user_id!("@alice:localhost");
+    let initial = vec![
+        message(
+            "$mention",
+            sender.as_str(),
+            2_000,
+            "direct mention",
+            Some(own_user.as_str()),
+        ),
+        message(
+            "$own-mention",
+            own_user.as_str(),
+            2_100,
+            "own event",
+            Some(own_user.as_str()),
+        ),
+        message(
+            "$unrelated",
+            sender.as_str(),
+            2_200,
+            "ordinary message",
+            None,
+        ),
+    ];
+    let feed = SlidingFeed::new(room_id.to_owned(), initial.clone());
+    feed.mount(&server).await;
+
+    let (engine, handle, mut events) = Engine::from_client(
+        client,
+        EngineConfig::default().with_initial_history_limit(0),
+    )
+    .await
+    .unwrap();
+    let running = tokio::spawn(engine.run());
+
+    let first = mentions_page(&mut events, room_id, |page| !page.entries.is_empty()).await;
+    assert_eq!(entry_ids(&first), HashSet::from(["$mention".to_owned()]));
+    assert_eq!(first.unread_count, 1);
+    let first_boundary = first.boundary.clone();
+
+    wait_for_requests(&feed, 3).await;
+    let replayed = handle.mentions_page(None, 50).await.unwrap();
+    assert_eq!(entry_ids(&replayed), HashSet::from(["$mention".to_owned()]));
+
+    let key = replayed.entries[0].key.clone();
+    handle
+        .set_mentions_read(vec![key.clone()], true)
+        .await
+        .unwrap();
+    let read = handle.mentions_page(None, 50).await.unwrap();
+    assert_eq!(read.unread_count, 0);
+
+    feed.replace(
+        room_id,
+        [
+            initial,
+            vec![message(
+                "$older-mention",
+                sender.as_str(),
+                1_000,
+                "older direct mention",
+                Some(own_user.as_str()),
+            )],
+        ]
+        .concat(),
+    );
+    let updated = mentions_page(&mut events, room_id, |page| page.entries.len() == 2).await;
+    assert_eq!(
+        entry_ids(&updated),
+        HashSet::from(["$mention".to_owned(), "$older-mention".to_owned(),])
+    );
+
+    handle
+        .mark_mentions_read_through(first_boundary)
+        .await
+        .unwrap();
+    let after_boundary = handle.mentions_page(None, 50).await.unwrap();
+    let read_states: Vec<_> = after_boundary
+        .entries
+        .iter()
+        .map(|entry| (entry.key.event_id.to_string(), entry.read))
+        .collect();
+    assert!(read_states.contains(&("$mention".to_owned(), true)));
+    assert!(read_states.contains(&("$older-mention".to_owned(), false)));
+    assert_eq!(after_boundary.unread_count, 1);
+
+    shut_down(&handle, &mut events, running).await;
+}
+
+#[tokio::test]
+async fn edits_can_remove_and_restore_a_mention_until_redaction_removes_its_target() {
+    let server = MatrixMockServer::new().await;
+    let room_id = room_id!("!mentions-edits:localhost");
+    let (client, own_user) = joined_client(&server, room_id).await;
+    let sender = user_id!("@alice:localhost");
+    let original = message(
+        "$edited-target",
+        sender.as_str(),
+        1_000,
+        "original mention",
+        Some(own_user.as_str()),
+    );
+    let removal = json!({
+        "type": "m.room.message",
+        "event_id": "$remove-edit",
+        "sender": sender,
+        "origin_server_ts": 2_000,
+        "content": {
+            "msgtype": "m.text",
+            "body": "* edited without a mention",
+            "m.relates_to": { "rel_type": "m.replace", "event_id": "$edited-target" },
+            "m.new_content": { "msgtype": "m.text", "body": "edited without a mention" },
+        },
+    });
+    let addition = json!({
+        "type": "m.room.message",
+        "event_id": "$add-edit",
+        "sender": sender,
+        "origin_server_ts": 3_000,
+        "content": {
+            "msgtype": "m.text",
+            "body": "* edited to mention you",
+            "m.relates_to": { "rel_type": "m.replace", "event_id": "$edited-target" },
+            "m.new_content": {
+                "msgtype": "m.text",
+                "body": "edited to mention you",
+                "m.mentions": { "user_ids": [own_user.as_str()] },
+            },
+        },
+    });
+    let redaction = json!({
+        "type": "m.room.redaction",
+        "event_id": "$redaction",
+        "sender": sender,
+        "origin_server_ts": 4_000,
+        "redacts": "$edited-target",
+        "content": {},
+    });
+    let feed = SlidingFeed::new(room_id.to_owned(), vec![original.clone()]);
+    feed.mount(&server).await;
+
+    let (engine, handle, mut events) = Engine::from_client(
+        client,
+        EngineConfig::default().with_initial_history_limit(0),
+    )
+    .await
+    .unwrap();
+    let running = tokio::spawn(engine.run());
+
+    let discovered = mentions_page(&mut events, room_id, |page| !page.entries.is_empty()).await;
+    assert_eq!(
+        entry_ids(&discovered),
+        HashSet::from(["$edited-target".to_owned()])
+    );
+
+    feed.replace(room_id, vec![original.clone(), removal.clone()]);
+    let removed = mentions_page(&mut events, room_id, |page| {
+        page.revision > discovered.revision && page.entries.is_empty()
+    })
+    .await;
+    assert!(removed.entries.is_empty());
+    assert_eq!(
+        handle
+            .mention_context(room_id, ruma::event_id!("$edited-target"))
+            .await
+            .unwrap_err()
+            .kind,
+        macltok::ErrorKind::EventNotFound
+    );
+
+    feed.replace(room_id, vec![original.clone(), removal, addition]);
+    let restored = mentions_page(&mut events, room_id, |page| {
+        page.revision > removed.revision && entry_ids(page).contains("$edited-target")
+    })
+    .await;
+    assert_eq!(
+        entry_ids(&restored),
+        HashSet::from(["$edited-target".to_owned()])
+    );
+
+    feed.replace(room_id, vec![original, redaction]);
+    let redacted = mentions_page(&mut events, room_id, |page| {
+        page.revision > restored.revision && page.entries.is_empty()
+    })
+    .await;
+    assert!(redacted.entries.is_empty());
+    assert_eq!(
+        handle
+            .mention_context(room_id, ruma::event_id!("$edited-target"))
+            .await
+            .unwrap_err()
+            .kind,
+        macltok::ErrorKind::EventNotFound
+    );
+
+    shut_down(&handle, &mut events, running).await;
+}
+
+#[tokio::test]
+async fn room_mentions_require_power_while_muted_direct_mentions_remain_and_ignored_senders_drop() {
+    let server = MatrixMockServer::new().await;
+    let client = server.client_builder().build().await;
+    let own_user = client.user_id().unwrap().to_owned();
+    let room_mention_room = room_id!("!room-mention-policy:localhost");
+    let muted_room = room_id!("!muted-mention-policy:localhost");
+    let ignored_sender = user_id!("@ignored:localhost");
+    let sender = user_id!("@alice:localhost");
+    let mut rules = Ruleset::server_default(&own_user);
+    rules.override_.shift_insert(
+        1,
+        NewConditionalPushRule::new(
+            "mute-inbox-room".to_owned(),
+            vec![PushCondition::EventMatch(EventMatchConditionData::new(
+                "room_id".to_owned(),
+                muted_room.to_string(),
+            ))],
+            Vec::new(),
+        )
+        .into(),
+    );
+    server
+        .mock_sync()
+        .ok_and_run(&client, {
+            let own_user = own_user.clone();
+            let ignored_sender = ignored_sender.to_owned();
+            move |builder| {
+                let factory = EventFactory::new();
+                builder.add_global_account_data(factory.push_rules(rules));
+                builder.add_global_account_data(factory.ignored_user_list([ignored_sender]));
+                builder.add_joined_room(
+                    JoinedRoomBuilder::new(room_mention_room)
+                        .add_state_event(
+                            EventFactory::new()
+                                .room(room_mention_room)
+                                .member(&own_user),
+                        )
+                        .add_state_event(
+                            EventFactory::new()
+                                .room(room_mention_room)
+                                .default_power_levels()
+                                .sender(&own_user),
+                        ),
+                );
+                builder.add_joined_room(
+                    JoinedRoomBuilder::new(muted_room)
+                        .add_state_event(EventFactory::new().room(muted_room).member(&own_user))
+                        .add_state_event(
+                            EventFactory::new()
+                                .room(muted_room)
+                                .default_power_levels()
+                                .sender(&own_user),
+                        ),
+                );
+            }
+        })
+        .await;
+
+    let feed = SlidingFeed::new(
+        room_mention_room.to_owned(),
+        vec![room_mention(
+            "$unauthorized-room-mention",
+            sender.as_str(),
+            3_000,
+        )],
+    );
+    feed.mount(&server).await;
+    let muted_events = vec![message(
+        "$muted-direct-mention",
+        sender.as_str(),
+        2_000,
+        "muted direct mention",
+        Some(own_user.as_str()),
+    )];
+    let ignored = message(
+        "$ignored-direct-mention",
+        ignored_sender.as_str(),
+        1_000,
+        "ignored direct mention",
+        Some(own_user.as_str()),
+    );
+    let mut muted_events = muted_events;
+    muted_events.push(ignored);
+    feed.add_room(muted_room, muted_events);
+
+    let (engine, handle, mut events) = Engine::from_client(
+        client,
+        EngineConfig::default().with_initial_history_limit(0),
+    )
+    .await
+    .unwrap();
+    let running = tokio::spawn(engine.run());
+
+    let page = mentions_page(&mut events, room_mention_room, |page| {
+        page.entries
+            .iter()
+            .any(|entry| entry.key.event_id.as_str() == "$muted-direct-mention")
+    })
+    .await;
+    assert_eq!(
+        entry_ids(&page),
+        HashSet::from(["$muted-direct-mention".to_owned()])
+    );
+    assert!(page.entries[0].notification_suppressed);
+    assert!(!entry_ids(&page).contains("$unauthorized-room-mention"));
+    assert!(!entry_ids(&page).contains("$ignored-direct-mention"));
+    let room_ids: HashSet<_> = page
+        .entries
+        .iter()
+        .map(|entry| entry.key.room_id.clone())
+        .collect();
+    assert!(room_ids.contains(&muted_room.to_owned()));
+
+    shut_down(&handle, &mut events, running).await;
+}
+
+#[tokio::test]
+async fn event_context_uses_independent_direction_limits_and_saved_mention_context_is_offline() {
+    let server = MatrixMockServer::new().await;
+    let room_id = room_id!("!mentions-context:localhost");
+    let (client, own_user) = joined_client(&server, room_id).await;
+    let mention_id = event_id!("$mention-context");
+    let context_id = event_id!("$manual-context");
+    let mention_event = EventFactory::new()
+        .room(room_id)
+        .text_msg("mention with saved context")
+        .mentions(Mentions::with_user_ids([own_user.clone()]))
+        .event_id(mention_id)
+        .sender(&ALICE)
+        .into_event();
+    let context_event = EventFactory::new()
+        .room(room_id)
+        .text_msg("manually fetched context")
+        .event_id(context_id)
+        .sender(&ALICE)
+        .into_event();
+
+    server
+        .mock_room_event_context()
+        .room(room_id.to_owned())
+        .match_event_id()
+        .ok(RoomContextResponseTemplate::new(mention_event.clone())
+            .start("mention-before")
+            .end("mention-after"))
+        .expect(1)
+        .mount()
+        .await;
+    server
+        .mock_room_event_context()
+        .room(room_id.to_owned())
+        .match_event_id()
+        .ok(RoomContextResponseTemplate::new(context_event)
+            .start("manual-before")
+            .end("manual-after"))
+        .expect(1)
+        .mount()
+        .await;
+    mount_messages_page(&server, room_id, "b", "mention-before", 10).await;
+    mount_messages_page(&server, room_id, "f", "mention-after", 10).await;
+    mount_messages_page(&server, room_id, "b", "manual-before", 2).await;
+    mount_messages_page(&server, room_id, "f", "manual-after", 3).await;
+
+    let feed = SlidingFeed::new(
+        room_id.to_owned(),
+        vec![message(
+            mention_id.as_str(),
+            ALICE.as_str(),
+            5_000,
+            "mention with saved context",
+            Some(own_user.as_str()),
+        )],
+    );
+    feed.mount(&server).await;
+    let (engine, handle, mut events) = Engine::from_client(
+        client,
+        EngineConfig::default().with_initial_history_limit(0),
+    )
+    .await
+    .unwrap();
+    let running = tokio::spawn(engine.run());
+
+    let captured = mentions_page_with_diagnostics(
+        &mut events,
+        room_id,
+        |page| {
+            page.entries.iter().any(|entry| {
+                entry.key.event_id == mention_id
+                    && matches!(&entry.capture, macltok::MentionCaptureState::Partial)
+            })
+        },
+        Some(&server),
+    )
+    .await;
+    let saved = handle.mention_context(room_id, mention_id).await.unwrap();
+    assert!(saved.context.is_some());
+    assert!(matches!(saved.state, macltok::MentionCaptureState::Partial));
+
+    let before_saved_request_count = server
+        .server()
+        .received_requests()
+        .await
+        .unwrap()
+        .iter()
+        .filter(|request| request.url.path().contains("/context/$mention-context"))
+        .count();
+    let _ = handle.mention_context(room_id, mention_id).await.unwrap();
+    let after_saved_request_count = server
+        .server()
+        .received_requests()
+        .await
+        .unwrap()
+        .iter()
+        .filter(|request| request.url.path().contains("/context/$mention-context"))
+        .count();
+    assert_eq!(after_saved_request_count, before_saved_request_count);
+
+    let context = handle
+        .event_context(room_id, context_id, 2, 3)
+        .await
+        .unwrap();
+    assert_eq!(context.start_token.as_deref(), Some("manual-before-next"));
+    assert_eq!(context.end_token.as_deref(), Some("manual-after-next"));
+
+    let requests = server.server().received_requests().await.unwrap();
+    let context_limits: Vec<_> = requests
+        .iter()
+        .filter(|request| request.url.path().contains("/context/"))
+        .map(|request| {
+            request
+                .url
+                .query_pairs()
+                .find(|(key, _)| key == "limit")
+                .map(|(_, value)| value.into_owned())
+                .unwrap()
+        })
+        .collect();
+    assert_eq!(context_limits, ["0", "0"]);
+    let queries: Vec<_> = requests
+        .iter()
+        .filter(|request| request.url.path().ends_with("/messages"))
+        .map(|request| {
+            let query: std::collections::HashMap<_, _> =
+                request.url.query_pairs().into_owned().collect();
+            (
+                query.get("dir").cloned().unwrap(),
+                query.get("from").cloned().unwrap(),
+                query
+                    .get("limit")
+                    .cloned()
+                    .unwrap_or_else(|| "10".to_owned()),
+            )
+        })
+        .collect();
+    assert!(queries.contains(&("b".to_owned(), "mention-before".to_owned(), "10".to_owned())));
+    assert!(queries.contains(&("f".to_owned(), "mention-after".to_owned(), "10".to_owned())));
+    assert!(queries.contains(&("b".to_owned(), "manual-before".to_owned(), "2".to_owned())));
+    assert!(queries.contains(&("f".to_owned(), "manual-after".to_owned(), "3".to_owned())));
+    assert_eq!(captured.unread_count, 1);
+
+    shut_down(&handle, &mut events, running).await;
+    server.server().verify().await;
+}
+
+#[cfg(feature = "sqlite")]
+#[tokio::test]
+async fn sqlite_mentions_survive_engine_shutdown_and_session_resume() {
+    static NEXT_TEMPORARY_PATH: AtomicUsize = AtomicUsize::new(0);
+
+    let server = MatrixMockServer::new().await;
+    server
+        .mock_versions()
+        .with_simplified_sliding_sync()
+        .ok()
+        .mount()
+        .await;
+    server.mock_login().ok().mount().await;
+
+    let root = std::env::temp_dir().join(format!(
+        "macltok-mentions-inbox-{}-{}",
+        std::process::id(),
+        NEXT_TEMPORARY_PATH.fetch_add(1, Ordering::Relaxed)
+    ));
+    let store_path = root.join("store");
+    let sessions_path = root.join("records").join("session");
+    let sessions = Arc::new(EncryptedSessionStore::file(
+        &sessions_path,
+        StoreConfig::sqlite(&store_path, "mentions inbox test passphrase"),
+    ));
+    let room_id = room_id!("!mentions-resume:matrix.org");
+    let own_user = user_id!("@cheeky_monkey:matrix.org");
+    let feed = SlidingFeed::new(
+        room_id.to_owned(),
+        vec![message(
+            "$durable-mention",
+            "@alice:matrix.org",
+            7_000,
+            "persist this mention",
+            Some(own_user.as_str()),
+        )],
+    );
+    feed.set_required_state(
+        room_id,
+        vec![json!({
+            "type": "m.room.member",
+            "event_id": "$joined-member",
+            "sender": own_user,
+            "state_key": own_user,
+            "origin_server_ts": 1,
+            "content": { "membership": "join" },
+        })],
+    );
+    feed.mount(&server).await;
+
+    let config = EngineConfig::default().with_initial_history_limit(0);
+    let session = Session::login_password(
+        PasswordLogin::new(server.uri(), "example", "wordpass").allow_insecure_loopback(true),
+        sessions.clone(),
+    )
+    .await
+    .unwrap();
+    let (engine, handle, mut events) = session.build(config.clone()).await.unwrap();
+    let running = tokio::spawn(engine.run());
+    let first = mentions_page(&mut events, room_id, |page| !page.entries.is_empty()).await;
+    assert_eq!(
+        entry_ids(&first),
+        HashSet::from(["$durable-mention".to_owned()])
+    );
+    shut_down(&handle, &mut events, running).await;
+    drop(handle);
+
+    let Some(Restore::Resumed(session)) = Session::restore(sessions.clone()).await.unwrap() else {
+        panic!("the saved session did not resume");
+    };
+    let (engine, handle, mut events) = session.build(config).await.unwrap();
+    let running = tokio::spawn(engine.run());
+    receive_until(&mut events, |event| {
+        matches!(event, Event::Authenticated { .. })
+    })
+    .await;
+    let resumed = handle.mentions_page(None, 50).await.unwrap();
+    assert_eq!(
+        entry_ids(&resumed),
+        HashSet::from(["$durable-mention".to_owned()])
+    );
+    assert_eq!(resumed.unread_count, 1);
+    shut_down(&handle, &mut events, running).await;
+    drop(handle);
+
+    sessions.discard().await.unwrap();
+    std::fs::remove_dir_all(root).unwrap();
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn mentions_command_and_page_round_trip_through_serde() {
+    let command = MentionsCommand::ReadThrough(MentionsBoundary {
+        account: user_id!("@alice:example.org").to_owned(),
+        revision: 7,
+    });
+    let encoded_command = serde_json::to_value(&command).unwrap();
+    let decoded_command: MentionsCommand = serde_json::from_value(encoded_command).unwrap();
+    assert_eq!(decoded_command, command);
+
+    let page = MentionsPage {
+        entries: Vec::new(),
+        next_cursor: Some("opaque cursor".to_owned()),
+        end_reached: false,
+        coverage: MentionCoverage::default(),
+        unread_count: 0,
+        revision: 7,
+        boundary: MentionsBoundary {
+            account: user_id!("@alice:example.org").to_owned(),
+            revision: 7,
+        },
+    };
+    let encoded_page = serde_json::to_value(&page).unwrap();
+    let decoded_page: MentionsPage = serde_json::from_value(encoded_page).unwrap();
+    assert_eq!(decoded_page, page);
+}

Added file: tests/mentions_late_decryption.rs+207 additions@@ -0,0 +1,207 @@
+mod support;
+
+use std::sync::{
+    Arc,
+    atomic::{AtomicUsize, Ordering},
+};
+use std::time::Duration;
+
+use macltok::{Engine, EngineConfig, Event, EventStream, MentionsPage};
+use matrix_sdk::{
+    ruma::{RoomVersionId, device_id, event_id, room_id, user_id},
+    test_utils::mocks::MatrixMockServer,
+};
+use matrix_sdk_test::{JoinedRoomBuilder, event_factory::EventFactory};
+use serde_json::{Value, json};
+use support::shut_down;
+use wiremock::{
+    Mock, Request, Respond, ResponseTemplate,
+    matchers::{method, path},
+};
+
+const SLIDING_SYNC_PATH: &str = "/_matrix/client/unstable/org.matrix.simplified_msc3575/sync";
+
+struct EncryptedSlidingFeed {
+    room_id: String,
+    event: Value,
+    requests: Arc<AtomicUsize>,
+}
+
+impl Clone for EncryptedSlidingFeed {
+    fn clone(&self) -> Self {
+        Self {
+            room_id: self.room_id.clone(),
+            event: self.event.clone(),
+            requests: self.requests.clone(),
+        }
+    }
+}
+
+impl EncryptedSlidingFeed {
+    async fn mount(&self, server: &MatrixMockServer) {
+        Mock::given(method("POST"))
+            .and(path(SLIDING_SYNC_PATH))
+            .respond_with(self.clone())
+            .mount(server.server())
+            .await;
+    }
+}
+
+impl Respond for EncryptedSlidingFeed {
+    fn respond(&self, _request: &Request) -> ResponseTemplate {
+        let request = self.requests.fetch_add(1, Ordering::AcqRel);
+        ResponseTemplate::new(200)
+            .set_delay(Duration::from_millis(20))
+            .set_body_json(json!({
+                "txn_id": null,
+                "pos": format!("late-decryption-{request}"),
+                "lists": {},
+                "rooms": {
+                    (self.room_id.clone()): {
+                        "initial": request == 0,
+                        "required_state": [],
+                        "timeline": [self.event.clone()],
+                    }
+                },
+                "extensions": {},
+            }))
+    }
+}
+
+async fn mentions_page(
+    events: &mut EventStream,
+    room_id: &ruma::RoomId,
+    predicate: impl Fn(&MentionsPage) -> bool,
+) -> MentionsPage {
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while let Some(event) = events.recv().await {
+            match event {
+                Event::TimelineReset { timeline_id, .. } if timeline_id.room_id() == room_id => {
+                    panic!("the unopened room produced a timeline reset");
+                }
+                Event::MentionsChanged(update) if predicate(&update.snapshot) => {
+                    return update.snapshot;
+                }
+                _ => {}
+            }
+        }
+        panic!("event stream closed before the expected mentions update");
+    })
+    .await
+    .expect("expected mentions update did not arrive")
+}
+
+async fn wait_for_requests(feed: &EncryptedSlidingFeed, minimum: usize) {
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while feed.requests.load(Ordering::Acquire) < minimum {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("the sliding sync feed did not receive another request");
+}
+
+#[tokio::test]
+async fn late_room_key_updates_the_production_mentions_inbox_once() {
+    let server = MatrixMockServer::new().await;
+    server.mock_crypto_endpoints_preset().await;
+    let alice_id = user_id!("@alice:localhost");
+    let bob_id = user_id!("@bob:localhost");
+    let room_id = room_id!("!mentions-late-decryption:localhost");
+    let event_id = event_id!("$late-production-mention");
+    let alice = server
+        .client_builder_for_crypto_end_to_end(alice_id, device_id!("ALICEDEVICE"))
+        .build()
+        .await;
+    let bob = server
+        .client_builder_for_crypto_end_to_end(bob_id, device_id!("BOBDEVICE"))
+        .build()
+        .await;
+    bob.event_cache().subscribe().unwrap();
+    server.exchange_e2ee_identities(&alice, &bob).await;
+
+    let factory = EventFactory::new().room(room_id).sender(alice_id);
+    let joined = JoinedRoomBuilder::new(room_id)
+        .add_state_event(factory.create(alice_id, RoomVersionId::V1))
+        .add_state_event(factory.room_encryption())
+        .add_state_event(factory.member(alice_id))
+        .add_state_event(factory.member(bob_id));
+    server.sync_room(&alice, joined.clone()).await;
+    server.sync_room(&bob, joined).await;
+
+    let room = alice.get_room(room_id).unwrap();
+    let (encrypted_event, send) = server.mock_room_send().ok_with_capture(event_id, alice_id);
+    let _send = send.mock_once().mount_as_scoped().await;
+    let (_keys, room_key) = server.mock_capture_put_to_device(alice_id).await;
+    server
+        .mock_get_members()
+        .ok(vec![
+            factory.member(alice_id).into_raw(),
+            factory.member(bob_id).into_raw(),
+        ])
+        .mock_once()
+        .mount()
+        .await;
+    room.send_raw(
+        "m.room.message",
+        json!({
+            "msgtype": "m.text",
+            "body": "a private mention",
+            "m.mentions": { "user_ids": [bob_id] }
+        }),
+    )
+    .await
+    .unwrap();
+    let encrypted_event = encrypted_event.await.unwrap();
+    let room_key = room_key.await;
+    let encrypted_event: Value = serde_json::from_str(encrypted_event.json().get()).unwrap();
+
+    let feed = EncryptedSlidingFeed {
+        room_id: room_id.to_string(),
+        event: encrypted_event,
+        requests: Arc::new(AtomicUsize::new(0)),
+    };
+    feed.mount(&server).await;
+
+    let (engine, handle, mut events) = Engine::from_client(
+        bob.clone(),
+        EngineConfig::default().with_initial_history_limit(0),
+    )
+    .await
+    .unwrap();
+    let running = tokio::spawn(engine.run());
+
+    let unresolved = mentions_page(&mut events, room_id, |page| {
+        page.coverage.unresolved_candidates == 1
+    })
+    .await;
+    assert!(unresolved.entries.is_empty());
+
+    server
+        .mock_sync()
+        .ok_and_run(&bob, |sync| {
+            sync.add_to_device_event(room_key.deserialize_as().unwrap());
+        })
+        .await;
+
+    let decrypted = mentions_page(&mut events, room_id, |page| {
+        page.entries.len() == 1 && page.entries[0].key.event_id == event_id
+    })
+    .await;
+    assert_eq!(decrypted.entries.len(), 1);
+    assert_eq!(decrypted.entries[0].key.event_id, event_id);
+    assert_eq!(decrypted.coverage.unresolved_candidates, 0);
+
+    let replay_start = feed.requests.load(Ordering::Acquire);
+    wait_for_requests(&feed, replay_start + 3).await;
+    let replayed = handle.mentions_page(None, 50).await.unwrap();
+    assert_eq!(replayed.entries.len(), 1);
+    assert_eq!(replayed.entries[0].key.event_id, event_id);
+    while let Ok(event) = events.try_recv() {
+        if let Event::TimelineReset { timeline_id, .. } = event {
+            assert_ne!(timeline_id.room_id(), room_id);
+        }
+    }
+
+    shut_down(&handle, &mut events, running).await;
+}

Modified file: tests/mirror.rs+97 additions−2 deletions@@ -4,14 +4,15 @@ use std::time::Duration;
 
 use futures_util::StreamExt;
 use macltok::{
-    ClientHandle, Command, Engine, EngineConfig, Event, Mirror, MirrorHandle, StateChange,
+    ClientHandle, Command, ConnectionState, Engine, EngineConfig, Event, MentionCoverage,
+    MentionsBoundary, MentionsPage, MentionsUpdate, Mirror, MirrorHandle, StateChange,
     Subscription, TimelineChange, TimelineCommand, TimelineDiff, TimelineId, TimelineItem, Update,
     UploadOutcome,
 };
 use matrix_sdk::{
     ruma::{
         OwnedRoomId, OwnedTransactionId, TransactionId, api::client::sync::sync_events::v5,
-        event_id, room_id,
+        event_id, room_id, user_id,
     },
     test_utils::mocks::MatrixMockServer,
 };
@@ -433,3 +434,97 @@ async fn an_upload_ends_on_finished() {
     .await;
     assert!(harness.mirror.snapshot().uploads.is_empty());
 }
+
+#[tokio::test]
+async fn mentions_updates_require_the_current_account_and_revision() {
+    let harness = start(EngineConfig::default(), 256).await;
+    let mut updates = harness.mirror.subscribe();
+    let account = tokio::time::timeout(Duration::from_secs(5), async {
+        loop {
+            let state = harness.mirror.snapshot();
+            if state.mentions.is_some() {
+                break state.user_id.clone().unwrap();
+            }
+            updates.next().await.unwrap();
+        }
+    })
+    .await
+    .expect("the initial mentions snapshot did not arrive");
+    let mentions_update = |account, revision| {
+        Event::MentionsChanged(MentionsUpdate {
+            snapshot: MentionsPage {
+                entries: Vec::new(),
+                next_cursor: None,
+                end_reached: true,
+                coverage: MentionCoverage::default(),
+                unread_count: 0,
+                revision,
+                boundary: MentionsBoundary { account, revision },
+            },
+            upserts: Vec::new(),
+            removed: Vec::new(),
+        })
+    };
+
+    harness
+        .inject
+        .send(mentions_update(account.clone(), 100))
+        .unwrap();
+    next_matching(
+        &mut updates,
+        |change| matches!(change, StateChange::Mentions(update) if update.snapshot.revision == 100),
+    )
+    .await;
+    assert_eq!(
+        harness
+            .mirror
+            .snapshot()
+            .mentions
+            .as_ref()
+            .unwrap()
+            .revision,
+        100
+    );
+
+    harness
+        .inject
+        .send(mentions_update(account.clone(), 99))
+        .unwrap();
+    harness
+        .inject
+        .send(mentions_update(
+            user_id!("@other:localhost").to_owned(),
+            101,
+        ))
+        .unwrap();
+    harness
+        .inject
+        .send(Event::ConnectionChanged(ConnectionState::Stopped))
+        .unwrap();
+    next_matching(&mut updates, |change| {
+        matches!(change, StateChange::Connection(ConnectionState::Stopped))
+    })
+    .await;
+    assert_eq!(
+        harness
+            .mirror
+            .snapshot()
+            .mentions
+            .as_ref()
+            .unwrap()
+            .revision,
+        100
+    );
+
+    harness.inject.send(Event::LoggedOut).unwrap();
+    harness.inject.send(mentions_update(account, 102)).unwrap();
+    harness
+        .inject
+        .send(Event::ConnectionChanged(ConnectionState::Stopped))
+        .unwrap();
+    next_matching(&mut updates, |change| {
+        matches!(change, StateChange::Connection(ConnectionState::Stopped))
+    })
+    .await;
+    assert!(harness.mirror.snapshot().mentions.is_none());
+}

show truncated diff

macltok

Commit cbb715e11963

Commit `cbb715e11963`