Implement MAP_CLEAR operation (RTLM24) and fill in tests

Implement applyMapClearOperation which checks clearTimeserial
(RTLM24c), updates it (RTLM24d), then removes entries from the
internal data whose timeserial is nil or <= the clear serial
(RTLM24e). Returns a LiveMapUpdate with the removed keys (RTLM24f).

Note: this follows the WIP spec change in 91dd01c where MAP_CLEAR
removes entries from data rather than tombstoning them, since the
clearTimeserial guards on MAP_SET and MAP_REMOVE make tombstoning
redundant. TODO: bring in line with the final spec once Andrii has
finalised his PR.

Tests:
- RTLM24c: parameterised clearTimeserial check (4 cases)
- RTLM24: operation application with older, equal, newer, and nil
  timeserial entries
- RTLM15d8: routing through nosync_apply with subscriber emission
- RTO9a2a: routing through handleObjectProtocolMessage
- mapClearOperationMessage test factory

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: lawrence-forooghian

Sources/AblyLiveObjects/Internal/InternalDefaultLiveMap.swift

@@ -913,7 +913,33 @@ internal final class InternalDefaultLiveMap: Sendable {
         internal mutating func applyMapClearOperation(
             serial: String?,
         ) -> LiveObjectUpdate<DefaultLiveMapUpdate> {
-            fatalError("TODO: Not yet implemented")
+            guard let serial else {
+                return .noop
+            }
+
+            // RTLM24c
+            if let clearTimeserial, serial <= clearTimeserial {
+                return .noop
+            }
+
+            // RTLM24d
+            clearTimeserial = serial
+
+            // RTLM24e, RTLM24e1: entry timeserial is nil, or serial >= entry timeserial
+            let keysToRemove = data.filter { _, entry in
+                guard let entryTimeserial = entry.timeserial else {
+                    return true
+                }
+                return serial >= entryTimeserial
+            }.keys
+
+            for key in keysToRemove {
+                data.removeValue(forKey: key)
+            }
+
+            // RTLM24e1b, RTLM24f
+            let removedKeys = Dictionary(uniqueKeysWithValues: keysToRemove.map { ($0, LiveMapUpdateAction.removed) })
+            return .update(DefaultLiveMapUpdate(update: removedKeys))
         }
 
         /// Resets the map's data and emits a `removed` event for the existing keys, per RTO4b2 and RTO4b2a. This is to be used when an `ATTACHED` ProtocolMessage indicates that the only object in a channel is an empty root map.

Tests/AblyLiveObjectsTests/Helpers/TestFactories.swift

@@ -603,6 +603,23 @@ struct TestFactories {
         )
     }
 
+    /// Creates an InboundObjectMessage with a MAP_CLEAR operation
+    static func mapClearOperationMessage(
+        objectId: String = "map:test@123",
+        serial: String = "ts1",
+        siteCode: String = "site1",
+    ) -> InboundObjectMessage {
+        inboundObjectMessage(
+            operation: objectOperation(
+                action: .known(.mapClear),
+                objectId: objectId,
+                mapClear: WireMapClear(),
+            ),
+            serial: serial,
+            siteCode: siteCode,
+        )
+    }
+
     /// Creates an InboundObjectMessage with a MAP_CREATE operation
     static func mapCreateOperationMessage(
         objectId: String = "map:test@123",

Tests/AblyLiveObjectsTests/InternalDefaultLiveMapTests.swift

@@ -1383,10 +1383,106 @@ struct InternalDefaultLiveMapTests {
 
     /// Tests for `MAP_CLEAR` operations, covering RTLM24 specification points
     struct MapClearOperationTests {
+        // MARK: - RTLM24c Tests (clearTimeserial check)
+
+        // @spec RTLM24c
+        @Test(arguments: [
+            // serial < clearTimeserial: discard
+            (operationSerial: "ts4" as String?, clearTimeserial: "ts5", expectedApplied: false),
+            // serial == clearTimeserial: discard
+            (operationSerial: "ts5" as String?, clearTimeserial: "ts5", expectedApplied: false),
+            // serial > clearTimeserial: allow
+            (operationSerial: "ts6" as String?, clearTimeserial: "ts5", expectedApplied: true),
+            // serial is nil: discard
+            (operationSerial: nil as String?, clearTimeserial: "ts5", expectedApplied: false),
+        ] as [(operationSerial: String?, clearTimeserial: String, expectedApplied: Bool)])
+        func checksClearTimeserialBeforeApplying(operationSerial: String?, clearTimeserial: String, expectedApplied: Bool) throws {
+            let logger = TestLogger()
+            let internalQueue = TestFactories.createInternalQueue()
+            let delegate = MockLiveMapObjectsPoolDelegate(internalQueue: internalQueue)
+            let coreSDK = MockCoreSDK(channelState: .attaching, internalQueue: internalQueue)
+
+            // Given: a map with an existing entry and the specified clearTimeserial
+            let map = InternalDefaultLiveMap(
+                testsOnly_data: ["key1": TestFactories.internalMapEntry(timeserial: "ts1", data: ObjectData(string: "existing"))],
+                objectID: "arbitrary",
+                logger: logger,
+                internalQueue: internalQueue,
+                userCallbackQueue: .main,
+                clock: MockSimpleClock(),
+            )
+
+            var pool = ObjectsPool(logger: logger, internalQueue: internalQueue, userCallbackQueue: .main, clock: MockSimpleClock())
+            internalQueue.ably_syncNoDeadlock {
+                _ = map.nosync_replaceData(
+                    using: TestFactories.objectState(
+                        map: TestFactories.objectsMap(
+                            entries: ["key1": TestFactories.stringMapEntry(key: "key1", value: "existing").entry],
+                            clearTimeserial: clearTimeserial,
+                        ),
+                    ),
+                    objectMessageSerialTimestamp: nil,
+                    objectsPool: &pool,
+                )
+            }
+
+            // When: applying a MAP_CLEAR operation with the specified serial
+            let update = map.testsOnly_applyMapClearOperation(serial: operationSerial)
+
+            // Then: the operation is applied or discarded as expected
+            #expect(update.isNoop == !expectedApplied)
+            if expectedApplied {
+                #expect(try map.get(key: "key1", coreSDK: coreSDK, delegate: delegate) == nil)
+            } else {
+                #expect(try map.get(key: "key1", coreSDK: coreSDK, delegate: delegate)?.stringValue == "existing")
+            }
+        }
+
+        // MARK: - RTLM24 Tests (MAP_CLEAR operation application)
+
         // @spec RTLM24
+        // @spec RTLM24d
+        // @spec RTLM24e
+        // @spec RTLM24e1
+        // @spec RTLM24e1a
+        // @spec RTLM24e1b
+        // @spec RTLM24f
         @Test
-        func appliesMapClearOperation() {
-            Issue.record("TODO: Add tests for MAP_CLEAR operation application")
+        func appliesMapClearOperation() throws {
+            let logger = TestLogger()
+            let internalQueue = TestFactories.createInternalQueue()
+
+            // Given: a map with multiple entries at different timeserials, including one with nil timeserial
+            let map = InternalDefaultLiveMap(
+                testsOnly_data: [
+                    "olderThanClear": TestFactories.internalMapEntry(timeserial: "ts1", data: ObjectData(string: "value1")),
+                    "equalToClear": TestFactories.internalMapEntry(timeserial: "ts3", data: ObjectData(string: "value2")),
+                    "newerThanClear": TestFactories.internalMapEntry(timeserial: "ts5", data: ObjectData(string: "value3")),
+                    "nilTimeserial": TestFactories.internalMapEntry(timeserial: nil, data: ObjectData(string: "value4")),
+                ],
+                objectID: "arbitrary",
+                logger: logger,
+                internalQueue: internalQueue,
+                userCallbackQueue: .main,
+                clock: MockSimpleClock(),
+            )
+
+            // When: applying a MAP_CLEAR operation with serial "ts3"
+            let update = map.testsOnly_applyMapClearOperation(serial: "ts3")
+
+            // Then: entries with timeserial <= "ts3" or nil are removed from internal data, others remain
+            #expect(Set(map.testsOnly_data.keys) == ["newerThanClear"])
+
+            // RTLM24f: update contains exactly the removed keys
+            let mapUpdate = try #require(update.update)
+            #expect(mapUpdate.update == [
+                "olderThanClear": .removed,
+                "equalToClear": .removed,
+                "nilTimeserial": .removed,
+            ])
+
+            // RTLM24d: clearTimeserial should be set
+            #expect(map.testsOnly_clearTimeserial == "ts3")
         }
     }
 
@@ -1607,9 +1703,60 @@ struct InternalDefaultLiveMapTests {
         // @spec RTLM15d8
         // @spec RTLM15d8a
         // @spec RTLM15d8b
+        @available(iOS 17.0.0, tvOS 17.0.0, *)
         @Test
-        func appliesMapClearOperation() {
-            Issue.record("TODO: Add test for MAP_CLEAR operation routing (copy structure from the above existing tests for other operations; should also test that siteTimeserials is updated per RTLM15c)")
+        func appliesMapClearOperation() async throws {
+            let logger = TestLogger()
+            let internalQueue = TestFactories.createInternalQueue()
+            let delegate = MockLiveMapObjectsPoolDelegate(internalQueue: internalQueue)
+            let coreSDK = MockCoreSDK(channelState: .attaching, internalQueue: internalQueue)
+            let map = InternalDefaultLiveMap.createZeroValued(objectID: "arbitrary", logger: logger, internalQueue: internalQueue, userCallbackQueue: .main, clock: MockSimpleClock())
+
+            let subscriber = Subscriber<DefaultLiveMapUpdate, SubscribeResponse>(callbackQueue: .main)
+            try map.subscribe(listener: subscriber.createListener(), coreSDK: coreSDK)
+
+            // Set initial data
+            var pool = ObjectsPool(logger: logger, internalQueue: internalQueue, userCallbackQueue: .main, clock: MockSimpleClock())
+            let (key1, entry1) = TestFactories.stringMapEntry(key: "key1", value: "existing", timeserial: nil)
+            internalQueue.ably_syncNoDeadlock {
+                _ = map.nosync_replaceData(
+                    using: TestFactories.mapObjectState(
+                        siteTimeserials: [:],
+                        entries: [key1: entry1],
+                    ),
+                    objectMessageSerialTimestamp: nil,
+                    objectsPool: &pool,
+                )
+            }
+            #expect(try map.get(key: "key1", coreSDK: coreSDK, delegate: delegate)?.stringValue == "existing")
+
+            let operation = TestFactories.objectOperation(
+                action: .known(.mapClear),
+                mapClear: WireMapClear(),
+            )
+
+            // Apply MAP_CLEAR operation
+            let applied = internalQueue.ably_syncNoDeadlock {
+                map.nosync_apply(
+                    operation,
+                    source: .channel,
+                    objectMessageSerial: "ts1",
+                    objectMessageSiteCode: "site1",
+                    objectMessageSerialTimestamp: nil,
+                    objectsPool: &pool,
+                )
+            }
+            #expect(applied)
+
+            // Verify the operation was applied (the full logic of RTLM24 is tested elsewhere; we just check for some of its side effects here)
+            #expect(try map.get(key: "key1", coreSDK: coreSDK, delegate: delegate) == nil)
+            #expect(map.testsOnly_clearTimeserial == "ts1")
+            // Verify RTLM15c side-effect: site timeserial was updated
+            #expect(map.testsOnly_siteTimeserials == ["site1": "ts1"])
+
+            // Verify update was emitted per RTLM15d8a
+            let subscriberInvocations = await subscriber.getInvocations()
+            #expect(subscriberInvocations.map(\.0) == [.init(update: ["key1": .removed])])
         }
 
         // @specOneOf(5/5) RTLM15c - Tests that siteTimeserials is NOT updated when source is LOCAL

Tests/AblyLiveObjectsTests/InternalDefaultRealtimeObjectsTests.swift

@@ -1217,8 +1217,50 @@ struct InternalDefaultRealtimeObjectsTests {
 
             // @specOneOf(6/6) RTO9a2a3 - Tests MAP_CLEAR operation application
             @Test
-            func appliesMapClearOperation() {
-                Issue.record("TODO: Add test for MAP_CLEAR operation application (copy structure from the above existing tests for other operations)")
+            func appliesMapClearOperation() throws {
+                let internalQueue = TestFactories.createInternalQueue()
+                let realtimeObjects = InternalDefaultRealtimeObjectsTests.createDefaultRealtimeObjects(internalQueue: internalQueue)
+                let objectId = "map:test@123"
+
+                // Create a map object in the pool first
+                let (entryKey, entry) = TestFactories.stringMapEntry(key: "existingKey", value: "existingValue")
+                internalQueue.ably_syncNoDeadlock {
+                    realtimeObjects.nosync_handleObjectSyncProtocolMessage(
+                        objectMessages: [
+                            TestFactories.mapObjectMessage(
+                                objectId: objectId,
+                                siteTimeserials: ["site1": "ts1"],
+                                entries: [entryKey: entry],
+                            ),
+                        ],
+                        protocolMessageChannelSerial: nil,
+                    )
+                }
+
+                // Verify the object exists and has initial data
+                let map = try #require(realtimeObjects.testsOnly_objectsPool.entries[objectId]?.mapValue)
+                let coreSDK = MockCoreSDK(channelState: .attached, internalQueue: internalQueue)
+                let initialValue = try #require(map.get(key: "existingKey", coreSDK: coreSDK, delegate: realtimeObjects)?.stringValue)
+                #expect(initialValue == "existingValue")
+
+                // Create a MAP_CLEAR operation message
+                let operationMessage = TestFactories.mapClearOperationMessage(
+                    objectId: objectId,
+                    serial: "ts2", // Higher than existing "ts1"
+                    siteCode: "site1",
+                )
+
+                // Handle the object protocol message
+                internalQueue.ably_syncNoDeadlock {
+                    realtimeObjects.nosync_handleObjectProtocolMessage(objectMessages: [operationMessage])
+                }
+
+                // Verify the operation was applied by checking for side effects
+                // The full logic of applying the operation is tested in RTLM15; we just check for some of its side effects here
+                let finalValue = try map.get(key: "existingKey", coreSDK: coreSDK, delegate: realtimeObjects)
+                #expect(finalValue == nil) // Key should be removed by MAP_CLEAR
+                #expect(map.testsOnly_clearTimeserial == "ts2")
+                #expect(map.testsOnly_siteTimeserials["site1"] == "ts2")
             }
         }