Fix integration test specs based on sandbox behavior

Update REST integration test specs (auth, mutable messages, revoke
tokens) to align assertions with actual Ably sandbox behaviour.

Author: paddybyers

uts/rest/integration/auth.md

@@ -220,8 +220,14 @@ Tests that invalid API keys are rejected by the server.
 ### Setup
 ```pseudo
 channel_name = "test-RSA4-invalid-" + random_id()
+
+# Use the real app_id with a fabricated key to guarantee a 401 response.
+# Using a completely fake app ID (e.g. "invalid.key:secret") may return
+# 404 (app not found) instead of 401 (unauthorized), depending on the server.
+invalid_key = app_id + ".invalidKey:invalidSecret"
+
 client = Rest(options: ClientOptions(
-  key: "invalid.key:secret",
+  key: invalid_key,
   endpoint: "sandbox"
 ))
 ```
@@ -314,18 +320,17 @@ client = Rest(options: ClientOptions(
 
 ### Test Steps
 ```pseudo
-# Request to allowed channel should succeed
-allowed_result = AWAIT client.request("GET", "/channels/" + allowed_channel)
+# Publish to allowed channel should succeed — the JWT grants "publish" capability.
+# Note: Do NOT use client.request("GET", "/channels/...") here — that is a channel
+# status request which requires "channel-metadata" capability, not "publish".
+AWAIT client.channels.get(allowed_channel).publish(name: "test", data: "hello")
 
-# Request to denied channel should fail with 40160 (capability refused)
-AWAIT client.request("POST", "/channels/" + denied_channel + "/messages",
-  body: {"name": "test", "data": "hello"}
-) FAILS WITH error
+# Publish to denied channel should fail with 40160 (capability refused)
+AWAIT client.channels.get(denied_channel).publish(name: "test", data: "hello") FAILS WITH error
 ```
 
 ### Assertions
 ```pseudo
-ASSERT allowed_result.statusCode >= 200 AND allowed_result.statusCode < 300
 ASSERT error.code == 40160
 ASSERT error.statusCode == 401
 ```

uts/rest/integration/mutable_messages.md

@@ -33,6 +33,24 @@ AFTER ALL TESTS:
 - All clients use `endpoint: "sandbox"`
 - All channel names use the `mutable:` namespace prefix — the test app setup configures the `mutable` namespace with `mutableMessages: true`, which is required for getMessage, updateMessage, deleteMessage, appendMessage, and annotations
 
+### Annotation HTTP Body Format
+
+The annotation publish and delete endpoints (`POST /channels/{channel}/messages/{serial}/annotations`)
+expect the HTTP request body to be a **JSON array** containing a single annotation object:
+
+```json
+[{"type": "com.ably.reactions", "name": "like", "action": 0}]
+```
+
+Sending a bare object (not wrapped in an array) returns HTTP 400 "invalid request body".
+
+The `action` field is **required** by the server and must be set by the SDK:
+- `0` = `ANNOTATION_CREATE` (for publish)
+- `1` = `ANNOTATION_DELETE` (for delete)
+
+The SDK's `annotations.publish()` and `annotations.delete()` methods must set the
+`action` field and wrap the annotation in an array before sending.
+
 ---
 
 ## RSL1n — publish returns serials from sandbox
@@ -154,8 +172,14 @@ ASSERT update_result IS UpdateDeleteResult
 ASSERT update_result.versionSerial IS String
 ASSERT update_result.versionSerial.length > 0
 
-# Verify via getMessage
-updated_msg = AWAIT channel.getMessage(serial)
+# Verify via getMessage — poll until the update is visible
+updated_msg = poll_until(
+  condition: FUNCTION() =>
+    msg = AWAIT channel.getMessage(serial)
+    RETURN msg.action == MessageAction.MESSAGE_UPDATE,
+  interval: 500ms,
+  timeout: 10s
+)
 ASSERT updated_msg.name == "updated"
 ASSERT updated_msg.data == "updated-data"
 ASSERT updated_msg.action == MessageAction.MESSAGE_UPDATE
@@ -199,8 +223,14 @@ ASSERT delete_result IS UpdateDeleteResult
 ASSERT delete_result.versionSerial IS String
 ASSERT delete_result.versionSerial.length > 0
 
-# Verify via getMessage — action should be MESSAGE_DELETE
-deleted_msg = AWAIT channel.getMessage(serial)
+# Verify via getMessage — poll until the delete is visible
+deleted_msg = poll_until(
+  condition: FUNCTION() =>
+    msg = AWAIT channel.getMessage(serial)
+    RETURN msg.action == MessageAction.MESSAGE_DELETE,
+  interval: 500ms,
+  timeout: 10s
+)
 ASSERT deleted_msg.action == MessageAction.MESSAGE_DELETE
 ```
 
@@ -239,8 +269,14 @@ AWAIT channel.updateMessage(
   operation: MessageOperation(description: "second edit")
 )
 
-# Get version history
-versions = AWAIT channel.getMessageVersions(serial)
+# Poll version history until all versions appear
+versions = poll_until(
+  condition: FUNCTION() =>
+    result = AWAIT channel.getMessageVersions(serial)
+    RETURN result.items.length >= 3,
+  interval: 500ms,
+  timeout: 10s
+)
 ```
 
 ### Assertions
@@ -328,8 +364,14 @@ AWAIT channel.annotations.publish(serial, Annotation(
   name: "like"
 ))
 
-# Verify annotation exists
-annotations = AWAIT channel.annotations.get(serial)
+# Verify annotation exists — poll until it appears
+annotations = poll_until(
+  condition: FUNCTION() =>
+    result = AWAIT channel.annotations.get(serial)
+    RETURN result.items.length >= 1,
+  interval: 500ms,
+  timeout: 10s
+)
 ASSERT annotations.items.length >= 1
 
 found = false
@@ -382,8 +424,14 @@ AWAIT channel.annotations.publish(serial, Annotation(
   name: "heart"
 ))
 
-# Retrieve annotations
-result = AWAIT channel.annotations.get(serial)
+# Retrieve annotations — poll until both appear
+result = poll_until(
+  condition: FUNCTION() =>
+    r = AWAIT channel.annotations.get(serial)
+    RETURN r.items.length >= 2,
+  interval: 500ms,
+  timeout: 10s
+)
 ```
 
 ### Assertions

uts/rest/integration/revoke_tokens.md

@@ -17,6 +17,26 @@ All tests use JWTs generated using a third-party JWT library, signed with
 the key secret using HMAC-SHA256. This avoids needing to call `requestToken()`
 and keeps the tests self-contained.
 
+## Server Response Format
+
+The Ably server returns token revocation results as a **plain JSON array** of
+per-target results:
+
+```json
+[{"target": "clientId:xxx", "appliesAt": 1234567890, "issuedBefore": 1234567890}]
+```
+
+On failure for a specific target, the element contains an `error` field instead:
+
+```json
+[{"target": "invalidType:abc", "error": {"code": 40000, "statusCode": 400, "message": "..."}}]
+```
+
+There is no `BatchResult` envelope — the `successCount` and `failureCount` fields
+(RSA17c) must be computed **client-side** by counting elements with and without an
+`error` field. This is consistent with how batch presence responses work (see
+`batch_presence.md`).
+
 ## Sandbox Setup
 
 Tests run against the Ably Sandbox at `https://sandbox-rest.ably.io`.
@@ -55,7 +75,7 @@ the token must be rejected by the server.
 |------|-------------|
 | RSA17g | POST to `/keys/{keyName}/revokeTokens` |
 | RSA17b | Targets mapped to `type:value` strings |
-| RSA17c | Returns `BatchResult` with `successCount`, `failureCount`, `results` |
+| RSA17c | Returns per-target results; SDK computes `successCount`, `failureCount` client-side |
 | TRS2a | Success result contains `target` string |
 | TRS2b | Success result contains `appliesAt` timestamp |
 | TRS2c | Success result contains `issuedBefore` timestamp |
@@ -100,6 +120,8 @@ revoke_result = AWAIT key_client.auth.revokeTokens([
 ])
 
 # Step 3: Verify the revokeTokens response structure (RSA17c, TRS2)
+# Note: The server returns a plain array of per-target results.
+# successCount/failureCount are computed client-side (see Server Response Format).
 ASSERT revoke_result.successCount == 1
 ASSERT revoke_result.failureCount == 0
 ASSERT revoke_result.results.length == 1
@@ -210,6 +232,7 @@ revoke_result = AWAIT key_client.auth.revokeTokens(
   options: { issuedBefore: server_time, allowReauthMargin: true }
 )
 
+# successCount is computed client-side (see Server Response Format)
 ASSERT revoke_result.successCount == 1
 ASSERT revoke_result.results.length == 1
 
@@ -284,6 +307,7 @@ revoke_result = AWAIT key_client.auth.revokeTokens([
 ])
 
 # Step 3: Verify the response contains both success and failure
+# successCount/failureCount are computed client-side (see Server Response Format)
 ASSERT revoke_result.successCount == 1
 ASSERT revoke_result.failureCount == 1
 ASSERT revoke_result.results.length == 2