fire message update state sync events for attachments that are loaded later (#96)

* -

* Update DatabaseTickWaits.swift

* -

* -

* Rename attachmentRowIDs → attachmentLoadMessageRowIDs

The local in resolvePendingMessageHydrationChanges held message ROWIDs
(passed in as forMessageRowIDs), not attachment ROWIDs; rename so the
name matches what's actually inside.

Generated with [Indent](https://indent.com)
Co-Authored-By: KishanBagaria <KishanBagaria@users.noreply.github.com>

* Update MappedDatabaseRows.swift

---------

Co-authored-by: indent[bot] <216979840+indent[bot]@users.noreply.github.com>
Co-authored-by: KishanBagaria <KishanBagaria@users.noreply.github.com>

Author: KishanBagaria

src/IMessage/Sources/IMDatabase/Database/IMDatabase+Updates.swift

@@ -25,22 +25,25 @@ package struct UpdatedMessageChange {
     package let isNew: Bool
     package let wasRead: Bool
     package let wasEdited: Bool
-    package let isPreviewUpdate: Bool
+    /// A late-hydration update (link preview or attachment load surfacing after
+    /// the row was first emitted). Consumers treat it identically to an edit:
+    /// it forces a full repatch rather than a read-receipt patch.
+    package let isHydrationUpdate: Bool
 
     package init(
         rowID: Int,
         chatGUID: String,
         isNew: Bool,
         wasRead: Bool,
         wasEdited: Bool,
-        isPreviewUpdate: Bool = false
+        isHydrationUpdate: Bool = false
     ) {
         self.rowID = rowID
         self.chatGUID = chatGUID
         self.isNew = isNew
         self.wasRead = wasRead
         self.wasEdited = wasEdited
-        self.isPreviewUpdate = isPreviewUpdate
+        self.isHydrationUpdate = isHydrationUpdate
     }
 
     package func merging(_ other: UpdatedMessageChange) -> UpdatedMessageChange {
@@ -50,7 +53,7 @@ package struct UpdatedMessageChange {
             isNew: isNew || other.isNew,
             wasRead: wasRead || other.wasRead,
             wasEdited: wasEdited || other.wasEdited,
-            isPreviewUpdate: isPreviewUpdate || other.isPreviewUpdate
+            isHydrationUpdate: isHydrationUpdate || other.isHydrationUpdate
         )
     }
 }

src/IMessage/Sources/IMDatabase/Models/Attachment.swift

@@ -32,5 +32,11 @@ public extension Attachment {
         public static let recoverableError = Self(rawValue: 7)
         public static let rejected = Self(rawValue: 8)
         public static let thumbnail = Self(rawValue: 9)
+
+        /// A state the file will never recover from, so any waiter should give up
+        /// rather than poll out its full timeout budget.
+        public var isTerminalFailure: Bool {
+            self == .error || self == .recoverableError || self == .rejected
+        }
     }
 }

src/IMessage/Sources/IMDatabase/Models/MappedDatabaseRows.swift

@@ -236,6 +236,10 @@ public struct MappedAttachmentRow: MappedDatabaseRow {
     public let filePath: String?
     public let size: [String: Int]?
 
+    public var transferStateValue: Attachment.IMFileTransferState? {
+        transferState.map(Attachment.IMFileTransferState.init(rawValue:))
+    }
+
     public init(
         msgRowID: Int,
         filename: String?,

src/IMessage/Sources/IMessage/DatabaseTickWaits.swift

@@ -10,6 +10,7 @@ private let sentMessageLinkWaitTimeout: TimeInterval = 1.5
 private let databaseTickBackstopInterval: TimeInterval = 1.0
 private let loadedAttachmentMinimumRequeryInterval: TimeInterval = 0.25
 
+// todo: DatabaseTickWaits.{sentMessageIDs,sentThreadIDs} shouldn't exist, we get ServerEvents for new messages, use that
 enum DatabaseTickWaits {
     typealias SentMessageID = (rowID: Int, guid: String)
 

src/IMessage/Sources/IMessage/EventWatcher/EventWatcher+Updates.swift

@@ -14,9 +14,15 @@ struct TimestampedChatState {
     }
 }
 
-struct PendingLinkPreviewCandidate {
+enum PendingMessageHydrationKind {
+    case linkPreview
+    case attachmentLoad
+}
+
+struct PendingMessageHydrationCandidate {
     let firstSeen: Date
     let chatGUID: String
+    let kind: PendingMessageHydrationKind
 }
 
 final class EventWatcher {
@@ -28,14 +34,14 @@ final class EventWatcher {
     var chatStates = [String: TimestampedChatState]()
     var updatesCursor: MessageUpdatesCursor
     var pendingUnresolvedNewMessageRowIDs = OrderedDictionary<Int, Date>()
-    var pendingLinkPreviewCandidates = OrderedDictionary<Int, PendingLinkPreviewCandidate>()
+    var pendingMessageHydrationCandidates = OrderedDictionary<Int, PendingMessageHydrationCandidate>()
     /// Rows resolved during the current tick whose pending entries are cleared
     /// only after the tick's events are successfully sent. On a send failure we
     /// leave them pending so the next tick retries: the main-query cursor has
     /// already advanced past these rows, so the pending maps are their only
     /// recovery path. Repopulated from scratch on every tick.
     var newMessageRowIDsAwaitingSendCommit: [Int] = []
-    var linkPreviewRowIDsAwaitingSendCommit: [Int] = []
+    var messageHydrationRowIDsAwaitingSendCommit: [Int] = []
     /// One-shot timer that re-triggers a tick while pending resolution work
     /// remains, so it isn't stranded when the database otherwise goes quiet.
     var pendingWakeTask: Task<Void, Never>?

src/IMessage/Sources/IMessage/EventWatcher/EventWatcher.swift

@@ -459,23 +459,9 @@ public final class PlatformAPI {
             let guid = messageGUID(fromID: messageID)
             guard let msgRow = try db.mappedMessageRow(guid: guid) else { return nil }
 
-            let terminalFailureStates: Set<Attachment.IMFileTransferState> = [
-                .error,
-                .recoverableError,
-                .rejected,
-            ]
-
-            let attachmentRows: [MappedAttachmentRow] = try db.mappedAttachmentRows(messageRowIDs: [msgRow.rowID])
-
-            for attachmentRow in attachmentRows {
-                guard let rawTransferState = attachmentRow.transferState else { continue }
-                let transferState = Attachment.IMFileTransferState(rawValue: rawTransferState)
-                if terminalFailureStates.contains(transferState) {
-                    return transferState
-                }
-            }
-
-            return nil
+            return try db.mappedAttachmentRows(messageRowIDs: [msgRow.rowID])
+                .compactMap(\.transferStateValue)
+                .first { $0.isTerminalFailure }
         }
     }
 

src/IMessage/Sources/IMessage/PlatformAPI.swift

@@ -153,17 +153,18 @@ import Testing
         text: "https://fixture.example.invalid/link"
     )
     let watcher = try fixtureEventWatcher(fixture: fixture, lastRowID: rowID)
-    watcher.pendingLinkPreviewCandidates[rowID] = PendingLinkPreviewCandidate(
+    watcher.pendingMessageHydrationCandidates[rowID] = PendingMessageHydrationCandidate(
         firstSeen: Date().addingTimeInterval(-121),
-        chatGUID: fixture.chatGUID
+        chatGUID: fixture.chatGUID,
+        kind: .linkPreview
     )
 
     // Payload never landed; the candidate is past its budget and must be
     // dropped without emitting a spurious update.
     let events = try await watcher.collectMessageUpdateEvents()
 
     #expect(events.isEmpty)
-    #expect(watcher.pendingLinkPreviewCandidates[rowID] == nil)
+    #expect(watcher.pendingMessageHydrationCandidates[rowID] == nil)
     #expect(watcher.pendingWakeTask == nil)
 }
 
@@ -228,6 +229,167 @@ import Testing
     #expect(thirdTickEvents.isEmpty)
 }
 
+@Test func loadingAttachmentEmitsFullUpdateWhenTransferFinishes() async throws {
+    let fixture = try TahoeChatDatabaseFixture()
+    defer { fixture.cleanup() }
+
+    let rowID = 21
+    let attachmentRowID = 210
+    let messageGUID = "00000000-0000-4000-8000-000000000047"
+    try insertJoinedMessage(fixture: fixture, rowID: rowID, guid: messageGUID, text: "")
+    try fixture.insertAttachment(
+        rowID: attachmentRowID,
+        messageRowID: rowID,
+        guid: "00000000-0000-4000-8000-000000000210",
+        filename: "/tmp/fixture-loading.jpg",
+        totalBytes: 10,
+        transferState: Attachment.IMFileTransferState.transferring.rawValue
+    )
+    let watcher = try fixtureEventWatcher(fixture: fixture, lastRowID: rowID - 1)
+
+    let firstTickEvents = try await collectAndCommit(watcher)
+    let firstEventObject = try firstMessageEventObject(in: firstTickEvents)
+    let firstEntry = try firstMessageEntry(in: firstEventObject)
+    let loadingAttachment = try firstAttachment(in: firstEntry)
+
+    #expect(firstEventObject["mutationType"] as? String == "upsert")
+    #expect(loadingAttachment["loading"] as? Bool == true)
+    #expect(watcher.pendingMessageHydrationCandidates[rowID] != nil)
+    #expect(watcher.pendingWakeTask != nil)
+
+    try fixture.updateAttachmentTransferState(
+        rowID: attachmentRowID,
+        transferState: Attachment.IMFileTransferState.finished.rawValue
+    )
+
+    let secondTickEvents = try await collectAndCommit(watcher)
+    let secondEventObject = try firstMessageEventObject(in: secondTickEvents)
+    let patch = try firstMessageEntry(in: secondEventObject)
+    let loadedAttachment = try firstAttachment(in: patch)
+
+    #expect(secondTickEvents.count == 1)
+    #expect(secondEventObject["mutationType"] as? String == "update")
+    #expect(patch["id"] as? String == "\(messageGUID)_1")
+    #expect(loadedAttachment["loading"] as? Bool == false)
+    #expect(watcher.pendingMessageHydrationCandidates[rowID] == nil)
+    #expect(watcher.pendingWakeTask == nil)
+}
+
+@Test func pendingAttachmentLoadExpiresAfterTimeout() async throws {
+    let fixture = try TahoeChatDatabaseFixture()
+    defer { fixture.cleanup() }
+
+    let rowID = 22
+    try insertJoinedMessage(fixture: fixture, rowID: rowID, guid: "00000000-0000-4000-8000-000000000048", text: "")
+    try fixture.insertAttachment(
+        rowID: 220,
+        messageRowID: rowID,
+        filename: "/tmp/fixture-never-loads.jpg",
+        transferState: Attachment.IMFileTransferState.transferring.rawValue
+    )
+    let watcher = try fixtureEventWatcher(fixture: fixture, lastRowID: rowID)
+    watcher.pendingMessageHydrationCandidates[rowID] = PendingMessageHydrationCandidate(
+        firstSeen: Date().addingTimeInterval(-121),
+        chatGUID: fixture.chatGUID,
+        kind: .attachmentLoad
+    )
+
+    let events = try await watcher.collectMessageUpdateEvents()
+
+    #expect(events.isEmpty)
+    #expect(watcher.pendingMessageHydrationCandidates[rowID] == nil)
+    #expect(watcher.pendingWakeTask == nil)
+}
+
+@Test func multiAttachmentWaitsForAllTransfersBeforeUpdating() async throws {
+    let fixture = try TahoeChatDatabaseFixture()
+    defer { fixture.cleanup() }
+
+    let rowID = 23
+    let messageGUID = "00000000-0000-4000-8000-000000000049"
+    try insertJoinedMessage(fixture: fixture, rowID: rowID, guid: messageGUID, text: "")
+    try fixture.insertAttachment(
+        rowID: 230,
+        messageRowID: rowID,
+        guid: "00000000-0000-4000-8000-000000000230",
+        filename: "/tmp/fixture-album-1.jpg",
+        totalBytes: 10,
+        transferState: Attachment.IMFileTransferState.transferring.rawValue
+    )
+    try fixture.insertAttachment(
+        rowID: 231,
+        messageRowID: rowID,
+        guid: "00000000-0000-4000-8000-000000000231",
+        filename: "/tmp/fixture-album-2.jpg",
+        totalBytes: 10,
+        transferState: Attachment.IMFileTransferState.transferring.rawValue
+    )
+    let watcher = try fixtureEventWatcher(fixture: fixture, lastRowID: rowID - 1)
+
+    // First tick: both attachments loading -> candidate tracked, wake armed.
+    _ = try await collectAndCommit(watcher)
+    #expect(watcher.pendingMessageHydrationCandidates[rowID] != nil)
+    #expect(watcher.pendingWakeTask != nil)
+
+    // Only one attachment finishes -> message is not ready, so no event fires and
+    // the candidate stays pending (guards against album flicker).
+    try fixture.updateAttachmentTransferState(
+        rowID: 230,
+        transferState: Attachment.IMFileTransferState.finished.rawValue
+    )
+    let partialTickEvents = try await collectAndCommit(watcher)
+    #expect(partialTickEvents.isEmpty)
+    #expect(watcher.pendingMessageHydrationCandidates[rowID] != nil)
+    #expect(watcher.pendingWakeTask != nil)
+
+    // The second attachment finishes -> exactly one full update, candidate cleared.
+    try fixture.updateAttachmentTransferState(
+        rowID: 231,
+        transferState: Attachment.IMFileTransferState.finished.rawValue
+    )
+    let finalTickEvents = try await collectAndCommit(watcher)
+    let finalEventObject = try firstMessageEventObject(in: finalTickEvents)
+
+    #expect(finalTickEvents.count == 1)
+    #expect(finalEventObject["mutationType"] as? String == "update")
+    #expect(watcher.pendingMessageHydrationCandidates[rowID] == nil)
+    #expect(watcher.pendingWakeTask == nil)
+}
+
+@Test func failedAttachmentTransferDropsCandidateWithoutEmitting() async throws {
+    let fixture = try TahoeChatDatabaseFixture()
+    defer { fixture.cleanup() }
+
+    let rowID = 24
+    try insertJoinedMessage(fixture: fixture, rowID: rowID, guid: "00000000-0000-4000-8000-000000000050", text: "")
+    try fixture.insertAttachment(
+        rowID: 240,
+        messageRowID: rowID,
+        guid: "00000000-0000-4000-8000-000000000240",
+        filename: "/tmp/fixture-fails.jpg",
+        totalBytes: 10,
+        transferState: Attachment.IMFileTransferState.transferring.rawValue
+    )
+    let watcher = try fixtureEventWatcher(fixture: fixture, lastRowID: rowID - 1)
+
+    // First tick: attachment loading -> candidate tracked, wake armed.
+    _ = try await collectAndCommit(watcher)
+    #expect(watcher.pendingMessageHydrationCandidates[rowID] != nil)
+    #expect(watcher.pendingWakeTask != nil)
+
+    // Transfer fails terminally -> the candidate is dropped on the very next tick
+    // (no event, wake disarmed) instead of polling for the full hydration timeout.
+    try fixture.updateAttachmentTransferState(
+        rowID: 240,
+        transferState: Attachment.IMFileTransferState.error.rawValue
+    )
+    let events = try await collectAndCommit(watcher)
+
+    #expect(events.isEmpty)
+    #expect(watcher.pendingMessageHydrationCandidates[rowID] == nil)
+    #expect(watcher.pendingWakeTask == nil)
+}
+
 @Test func readAndPreviewChangesForSameRowEmitOneFullUpdate() async throws {
     let fixture = try TahoeChatDatabaseFixture()
     defer { fixture.cleanup() }
@@ -442,3 +604,8 @@ private func firstLink(in messageObject: JSONObject) throws -> JSONObject {
     let links = try #require(messageObject["links"] as? [JSONObject])
     return try #require(links.first)
 }
+
+private func firstAttachment(in messageObject: JSONObject) throws -> JSONObject {
+    let attachments = try #require(messageObject["attachments"] as? [JSONObject])
+    return try #require(attachments.first)
+}

src/IMessage/Sources/IMessageTests/EventWatcherUpdateTests.swift

@@ -106,6 +106,43 @@ final class TahoeChatDatabaseFixture {
         try database.execute(sqlWithoutEscaping: "UPDATE message SET payload_data = ? WHERE ROWID = ?", payloadData, rowID)
     }
 
+    func insertAttachment(
+        rowID: Int,
+        messageRowID: Int,
+        guid: String? = nil,
+        filename: String,
+        transferName: String? = nil,
+        totalBytes: Int = 0,
+        transferState: Int
+    ) throws {
+        try database.execute(
+            sqlWithoutEscaping: """
+            INSERT INTO attachment (ROWID, guid, original_guid, filename, transfer_name, total_bytes, transfer_state)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            rowID,
+            guid ?? "attachment-\(rowID)",
+            "original-attachment-\(rowID)",
+            filename,
+            transferName ?? (filename as NSString).lastPathComponent,
+            totalBytes,
+            transferState
+        )
+        try database.execute(
+            sqlWithoutEscaping: "INSERT INTO message_attachment_join (message_id, attachment_id) VALUES (?, ?)",
+            messageRowID,
+            rowID
+        )
+    }
+
+    func updateAttachmentTransferState(rowID: Int, transferState: Int) throws {
+        try database.execute(
+            sqlWithoutEscaping: "UPDATE attachment SET transfer_state = ? WHERE ROWID = ?",
+            transferState,
+            rowID
+        )
+    }
+
     private static func insertChatJoin(
         messageRowID: Int,
         chatRowID: Int,

src/IMessage/Sources/IMessageTests/TahoeChatDatabaseFixture.swift

@@ -17,6 +17,7 @@
 - [ ] separate `UserDefaults` somehow so that CLI and other consumers don't share the prefs
 - [ ] user manually killing the messages.app causes cli to not detect that ("Domain=NSOSStatusErrorDomain Code=-600 "procNotFound: no eligible process with specified descriptor"")
 - [ ] when scheduled messages are actually sent, send a message update event
+- [ ] surface terminal-failure attachment state so a failed/rejected download clears the loading spinner. Today `loading = transferState != .finished` (`MessageMapper+Attachments.swift:26`), so error/recoverableError/rejected (states 6/7/8, `Attachment.swift:31-33`) read as `loading: true` forever; `PlatformSDK.Attachment` (`PlatformSDKAttachment.swift:26`) has no failed flag. After the EventWatcher hydration path stops polling failed transfers, the last emitted state still says loading, so the consumer spins indefinitely. Needs: a failed/error field on the attachment type + mapper wiring + EventWatcher emitting it on terminal failure + consumer-side rendering. The EventWatcher hydration path already drops terminally-failed candidates via `IMFileTransferState.isTerminalFailure`.
 - [ ] perhaps move PlatformSDK to <https://github.com/TextsHQ/platform-sdk>
 
 - concurrency