test(uts): address review feedback — harden shared infra, fix test-resource leaks, correct docs

Review-driven fixes on the UTS refactoring (PR #1228 threads):

- uts infra: awaitState/awaitChannelState could double-resume their
  continuation (the state listener and the immediate check race on
  different threads; check-then-resume is not atomic). Use the atomic
  single-winner tryResume/completeResume pair (@InternalCoroutinesApi).
- liveobjects tests: dispose ObjectsPool in teardown where it leaked a
  GC coroutine + adapter subscription (LiveObjectTombstoneTest,
  DefaultRealtimeObjectAsyncTest), matching the documented S-4 contract;
  align ValueTypesTest to the dispose-before-unmockkAll ordering.
- liveobjects integration: retain the provisioned SandboxApp and delete
  it in tearDownAfterClass (best-effort, matching the :java suites).
- InternalLiveMapApiTest: replace the stale note claiming a real
  GET /time fires — setupSyncedChannel installs a MockHttpClient that
  answers /time locally; the unit tier is hermetic.
- deviations.md (:java): restructure into the canonical four-section
  format from writing-derived-tests.md (UTS Spec Errors / Failing Tests /
  Adapted Tests / Mock Infrastructure Limitations), preserving all
  recorded deviations; fix the RTN16g2 heading to describe the workaround
  rather than restate it as a requirement; drop the stale moved-pointer.
- uts/README.md: replace the invalid-Kotlin ellipsis with the real
  systemProperty expression from uts/build.gradle.kts.
- uts-to-kotlin skill: point the deviation checklist at the tier's module
  deviations file; spell out the full TestHelpers.kt path.

The ObjectsSyncTracker channelSerial regex finding is intentionally not
fixed here — tracked cross-SDK in ably/specification#520.

Verified: liveobjects unit 389/0; :java/:uts UTS unit 6/0, 3/0;
integration 29/0, 5/0, 4/0; codenarc + checkstyle green.

Author: sacOO7

.claude/skills/uts-to-kotlin/SKILL.md

@@ -645,7 +645,7 @@ For each test case, verify:
 Deviations are discovered by running, so this check applies in evaluate mode. For any place where the
 generated test diverges from the spec pseudocode (adapted assertion, env-gated skip, or omitted step):
 - [ ] A `// DEVIATION:` comment explains why
-- [ ] The deviation is recorded in `lib/src/test/kotlin/io/ably/lib/uts/deviations.md`
+- [ ] The deviation is recorded in the tier's module deviations file (see "Deviations file" above: `lib/src/test/kotlin/io/ably/lib/uts/deviations.md` for realtime/rest tiers, `liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/deviations.md` for objects tiers)
 
 If you find gaps during this review, fix them, then **re-run the audit script** until `missingInKotlin` /
 `orphanInKotlin` are empty and every `perTest` entry reconciles, and re-run Step 5 (compile) — and, in

.claude/skills/uts-to-kotlin/references/objects-mapping.md

@@ -726,7 +726,7 @@ reflection.
 
 The internal classes have `private constructor`s; each pairs with an `internal` companion factory that
 needs a `DefaultRealtimeObject`. Build one from the mocked adapter (helper already exists in
-`liveobjects/src/test/.../unit/TestHelpers.kt`):
+`liveobjects/src/test/kotlin/io/ably/lib/liveobjects/unit/TestHelpers.kt`):
 
 ```kotlin
 val ro = DefaultRealtimeObject("test", getMockAblyClientAdapter())

lib/src/test/kotlin/io/ably/lib/uts/deviations.md

@@ -1,24 +1,19 @@
-# SDK Deviations
-
-Deviations from the Ably spec identified during UTS test translation. Each entry records the spec point, what the spec requires, what the SDK actually does, and which test contains the deviation gate.
-
-**Scope:** this file now lives alongside the realtime UTS suites in the `:java` module
-(`lib/src/test/kotlin/io/ably/lib/uts/`) and holds deviations for the **realtime/rest tiers** it
-hosts. All **objects** tiers (unit, integration and proxy) moved to `:liveobjects`'s own test source
-set alongside the tests they document; their deviations (the typed-SDK / language adaptations, the
-intentional RTO18d entry, and any objects integration/proxy entries) are in
-`liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/deviations.md`. For the shared UTS infra these
-suites consume, the tier smoke examples, and the `RUN_DEVIATIONS` mechanism, see `uts/README.md`.
-
-Entries are grouped by actionability (shared taxonomy across both files; only groups with entries in
-this file appear as sections below):
-
-| Group | Meaning | Action |
-|---|---|---|
-| **1) Genuine SDK bugs — open** | runtime behaviour differs from the spec; ably-js is compliant | fix the SDK |
-| **2) Shared gap — open in both SDKs** | ably-java and ably-js deviate the same way | optional joint fix (spec is ahead of both) |
-| **3) Expected — typed-SDK / language adaptations** | not bugs: RTTS API partitioning, compile-time guarantees, internal-wire visibility | none — correct as documented |
-| **4) Intentional deviation** | deliberate SDK design choice; the spec point itself is questioned | none unless the spec is revised |
+# Deviations — UTS realtime/rest suites (`io.ably.lib.uts.*`)
+
+> **Scope:** this file lives alongside the realtime/rest UTS suites in the `:java` module
+> (`lib/src/test/kotlin/io/ably/lib/uts/`) and holds deviations for the **realtime/rest tiers** it
+> hosts. All **objects** tiers (unit, integration and proxy) moved to `:liveobjects`'s own test source
+> set alongside the tests they document; their deviations (the typed-SDK / language adaptations, the
+> intentional RTO18d entry, and any objects integration/proxy entries) are in
+> `liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/deviations.md`. For the shared UTS infra these
+> suites consume, the tier smoke examples, and the `RUN_DEVIATIONS` mechanism, see `uts/README.md`.
+>
+> Records every place a generated test deviates from its UTS spec, using the manual's **Recording
+> deviations** entry format: each entry records the spec point, what the spec requires, what the SDK
+> actually does, and which test carries the deviation gate. Every deviation recorded here is a
+> **genuine SDK bug** (open; ably-js is compliant — fix the SDK), stated per entry under **Status**; the
+> other actionability groups of the shared taxonomy (shared cross-SDK gap, typed-SDK / language
+> adaptations, intentional design divergence) only have entries in the objects file.
 
 > **Recently fixed and removed from this file:** RTO23e (`get()` now re-attaches a DETACHED channel —
 > mode-only check + ensure-active-channel) and RTO20e/RTO20e1 (event-driven `once(SYNCED)` waiters +
@@ -32,16 +27,48 @@ this file appear as sections below):
 
 ---
 
-# 1) Genuine SDK bugs — open (realtime module)
+## UTS Spec Errors
+
+*(none)*
+
+## Failing Tests
 
-*Runtime behaviour differs from the spec and ably-js is compliant — real bugs, pending an SDK fix.*
+*SDK non-compliance where the spec-correct assertion is present but skipped (env-gated behind `RUN_DEVIATIONS`). These are the primary output — each maps to a potential issue to file.*
 
 > ⚠ **RTL13b / RTL13c:** the channel-state UTS tests these two entries cite are **not currently part of the
 > uts suite** (no `RTL13*` tests or gates exist in `unit/realtime/` — only `ConnectionRecoveryTest.kt` is
 > translated). The entries are retained as confirmed SDK gaps (cross-checked against ably-js in
 > `ABLY-JS-JAVA-DEVIATIONS-COMPARISON.md`); re-verify them when the channels module translation lands.
+> (RTL13b is recorded under **Adapted Tests** — it adapts the test setup rather than env-gating an assertion.)
+
+### RTL13c — channelRetryTimeout not cancelled when connection leaves CONNECTED
+
+**Spec point:** RTL13c  
+**What the spec requires:** When the connection is no longer CONNECTED, any pending automatic channel reattach timer (channelRetryTimeout) must be cancelled. The channel should remain SUSPENDED without attempting to reattach until the connection is restored.  
+**What the SDK does:** The channelRetryTimeout fires regardless of connection state. When it fires while disconnected, the channel transitions to ATTACHING even though there is no active connection, and no ATTACH message can be sent.  
+**Tests affected:**
+- `RTL13c - automatic retry cancelled when connection is no longer CONNECTED` (RTL13c/retry-cancelled-disconnected-0) — the assertions `assertEquals(attachCountAfterDisconnect, attachCount)` and `assertEquals(ChannelState.suspended, channel.state)` are gated behind `RUN_DEVIATIONS`.
+
+**Status:** Open SDK bug — ably-js is compliant; fix the SDK.
+
+### RTN16f — msgSerial not initialised from recovery key on connect
+
+**Spec point:** RTN16f  
+**What the spec requires:** When instantiated with the `recover` option, the SDK initialises its internal `msgSerial` counter to the value stored in the recovery key, so the first published message carries that serial.  
+**What the SDK does:** `ConnectionManager.onConnected()` resets `msgSerial` to 0 whenever `connection.id` is null on the fresh client (line 1316), even when the `recover` option is set. The recovered serial is discarded.  
+**Workaround in tests:** The spec-correct assertion (`assertEquals(42L, msgSerial)`) is gated behind `RUN_DEVIATIONS`. A regression guard assertion (`assertEquals(0L, msgSerial)`) runs by default to catch any unintentional change to the SDK's actual behaviour.  
+**Tests affected:**
+- `RTN16f - recover option initializes msgSerial from recoveryKey` (RTN16f/recover-initializes-msgserial-0) — `assertEquals(42L, ...)` gated; `assertEquals(0L, ...)` added as regression guard.
+
+**Status:** Open SDK bug — ably-js is compliant; fix the SDK.
+
+## Adapted Tests
 
-## RTL13b — ATTACHING → SUSPENDED via `realtimeRequestTimeout` not implemented
+*SDK non-compliance where the test asserts the SDK's actual behaviour (or adapts its setup/stimulus to the SDK's reality) instead of using the spec's unreachable path. It passes, guards against regressions, and documents the deviation.*
+
+> ⚠ Not currently part of the uts suite — see the shared **RTL13b / RTL13c** caveat under **Failing Tests**.
+
+### RTL13b — ATTACHING → SUSPENDED via realtimeRequestTimeout not implemented
 
 **Spec point:** RTL13b  
 **What the spec requires:** If a channel's reattach request (triggered by RTL13a) does not receive a response within `realtimeRequestTimeout`, the channel must transition from ATTACHING to SUSPENDED and schedule a retry after `channelRetryTimeout`.  
@@ -53,19 +80,9 @@ this file appear as sections below):
 - `RTL13b - repeated failures cycle SUSPENDED to ATTACHING indefinitely` (RTL13b/repeated-failure-cycle-2) — mock sends DETACHED instead of withholding response
 - `RTL13c - automatic retry cancelled when connection is no longer CONNECTED` (RTL13c/retry-cancelled-disconnected-0) — setup path changed
 
----
-
-## RTL13c — channelRetryTimeout not cancelled when connection leaves CONNECTED
-
-**Spec point:** RTL13c  
-**What the spec requires:** When the connection is no longer CONNECTED, any pending automatic channel reattach timer (channelRetryTimeout) must be cancelled. The channel should remain SUSPENDED without attempting to reattach until the connection is restored.  
-**What the SDK does:** The channelRetryTimeout fires regardless of connection state. When it fires while disconnected, the channel transitions to ATTACHING even though there is no active connection, and no ATTACH message can be sent.  
-**Tests affected:**
-- `RTL13c - automatic retry cancelled when connection is no longer CONNECTED` (RTL13c/retry-cancelled-disconnected-0) — the assertions `assertEquals(attachCountAfterDisconnect, attachCount)` and `assertEquals(ChannelState.suspended, channel.state)` are gated behind `RUN_DEVIATIONS`.
-
----
+**Status:** Open SDK bug — ably-js is compliant; fix the SDK.
 
-## RTN16g2 — Fatal ERROR must be sent without closing the transport
+### RTN16g2 — the spec's fatal-ERROR-plus-close trigger can't drive this SDK to FAILED
 
 **Spec point:** RTN16g2  
 **What the spec requires:** Trigger FAILED state by sending a fatal ERROR message followed by closing the WebSocket (`send_to_client_and_close`), using error code 50000/statusCode 500.  
@@ -76,24 +93,8 @@ this file appear as sections below):
 **Tests affected:**
 - `RTN16g2 - createRecoveryKey returns null in inactive states and before first connect` (RTN16g2/recovery-key-null-inactive-0) — error code and send method changed.
 
----
-
-## RTN16f — msgSerial not initialised from recovery key on connect
-
-**Spec point:** RTN16f  
-**What the spec requires:** When instantiated with the `recover` option, the SDK initialises its internal `msgSerial` counter to the value stored in the recovery key, so the first published message carries that serial.  
-**What the SDK does:** `ConnectionManager.onConnected()` resets `msgSerial` to 0 whenever `connection.id` is null on the fresh client (line 1316), even when the `recover` option is set. The recovered serial is discarded.  
-**Workaround in tests:** The spec-correct assertion (`assertEquals(42L, msgSerial)`) is gated behind `RUN_DEVIATIONS`. A regression guard assertion (`assertEquals(0L, msgSerial)`) runs by default to catch any unintentional change to the SDK's actual behaviour.  
-**Tests affected:**
-- `RTN16f - recover option initializes msgSerial from recoveryKey` (RTN16f/recover-initializes-msgserial-0) — `assertEquals(42L, ...)` gated; `assertEquals(0L, ...)` added as regression guard.
-
----
-
+**Status:** Open SDK bug — ably-js is compliant; fix the SDK.
 
-# Objects deviations — moved
+## Mock Infrastructure Limitations
 
-All objects tiers (**unit, integration and proxy**) live in `:liveobjects`'s own test source set,
-and their deviation records (the typed-SDK / language adaptations, the former groups 3 & 4 as they
-applied to objects, and any objects integration/proxy entries) are in
-`liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/deviations.md`. This file keeps only the
-deviations for the realtime/rest tiers hosted in `:java`.
+*(none)*

liveobjects/src/test/kotlin/io/ably/lib/liveobjects/integration/setup/IntegrationTest.kt

@@ -91,7 +91,8 @@ abstract class IntegrationTest {
     @JvmStatic
     @AfterClass
     @Throws(Exception::class)
-    fun tearDownAfterClass() {
+    fun tearDownAfterClass(): Unit = runBlocking {
+      if (::sandbox.isInitialized) sandbox.delete()
     }
   }
 }

liveobjects/src/test/kotlin/io/ably/lib/liveobjects/integration/setup/Sandbox.kt

@@ -15,14 +15,17 @@ import kotlinx.coroutines.CompletableDeferred
  * canonical `test-app-setup.json` app spec); this type just carries the fields the local
  * client-factory extensions need.
  */
-class Sandbox private constructor(val appId: String, val apiKey: String) {
+class Sandbox private constructor(private val app: SandboxApp, val appId: String, val apiKey: String) {
   companion object {
     internal suspend fun createInstance(): Sandbox {
       val app = SandboxApp.create()
       // defaultKey is the full-capability "appId.keyId:keySecret" key (index 0 of the app spec)
-      return Sandbox(appId = app.appId, apiKey = app.defaultKey)
+      return Sandbox(app = app, appId = app.appId, apiKey = app.defaultKey)
     }
   }
+
+  /** Best-effort teardown of the provisioned sandbox app (see [SandboxApp.delete]). */
+  internal suspend fun delete() = app.delete()
 }
 
 internal fun Sandbox.createRealtimeClient(options: ClientOptions.() -> Unit): AblyRealtime {

liveobjects/src/test/kotlin/io/ably/lib/liveobjects/unit/DefaultRealtimeObjectAsyncTest.kt

@@ -20,13 +20,18 @@ import kotlin.test.assertFailsWith
  */
 class DefaultRealtimeObjectAsyncTest {
 
+  private val created = mutableListOf<DefaultRealtimeObject>()
+
   private fun newObject(): DefaultRealtimeObject =
-    DefaultRealtimeObject("ch", getMockAblyClientAdapter())
+    DefaultRealtimeObject("ch", getMockAblyClientAdapter()).also { created += it }
 
   private fun boom() = AblyException.fromErrorInfo(ErrorInfo("boom", 400, 40000))
 
   @After
-  fun tearDown() = unmockkAll() // getMockAblyClientAdapter uses mockkStatic - clean up global state
+  fun tearDown() {
+    created.forEach { it.objectsPool.dispose() } // the pool init starts a real GC coroutine
+    unmockkAll() // getMockAblyClientAdapter uses mockkStatic - clean up global state
+  }
 
   @Test
   fun asyncFutureCompletesWithResult() {

liveobjects/src/test/kotlin/io/ably/lib/liveobjects/unit/LiveObjectTombstoneTest.kt

@@ -29,16 +29,21 @@ import org.junit.Test
  */
 class LiveObjectTombstoneTest {
 
+  private lateinit var realtimeObject: DefaultRealtimeObject
+
   private fun rootMapWithNameEntry(): InternalLiveMap {
-    val realtimeObject = DefaultRealtimeObject("test", getMockAblyClientAdapter())
+    realtimeObject = DefaultRealtimeObject("test", getMockAblyClientAdapter())
     val map = InternalLiveMap.zeroValue("root", realtimeObject)
     map.data["name"] = LiveMapEntry(timeserial = "01", data = WireObjectData(string = "Alice"))
     map.siteTimeserials["site1"] = "00"
     return map
   }
 
   @After
-  fun tearDown() = unmockkAll() // getMockAblyClientAdapter uses mockkStatic - clean up global state
+  fun tearDown() {
+    realtimeObject.objectsPool.dispose() // the pool init starts a real GC coroutine
+    unmockkAll() // getMockAblyClientAdapter uses mockkStatic - clean up global state
+  }
 
   /**
    * @UTS objects/unit/RTLO4e10/object-delete-root-noop-0

liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/unit/InternalLiveMapApiTest.kt

@@ -29,10 +29,10 @@ import kotlin.test.assertTrue
  * mock's recorded `MessageFromClient` event log as the spec's `captured_messages` — see
  * [capturedObjectMessages].
  *
- * Note: evaluating a `LiveCounter`/`LiveMap` value type generates its objectId from server
- * time (RTO16), which the SDK fetches once per JVM via REST `GET /time` — the mock transport
- * does not intercept HTTP, so the first `*_CREATE` test in a run performs that single
- * unauthenticated request against the real endpoint.
+ * Note: evaluating a LiveCounter/LiveMap value type derives its objectId from server time
+ * (RTO16), which the SDK fetches via REST GET /time. The shared setupSyncedChannel installs a
+ * MockHttpClient (Helpers.kt) that answers /time locally, so these unit tests stay hermetic —
+ * no real network request is made, per the UTS unit-tier no-network contract.
  */
 class InternalLiveMapApiTest {
 

liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/unit/ValueTypesTest.kt

@@ -50,8 +50,8 @@ class ValueTypesTest {
 
     @AfterTest
     fun tearDown() {
-        unmockkAll()
         ro.objectsPool.dispose()
+        unmockkAll()
     }
 
     /**

uts/README.md

@@ -234,7 +234,12 @@ tasks.withType<Test>().configureEach {
     jvmArgs("--add-opens", "java.base/java.lang=ALL-UNNAMED")
     // Propagate a local proxy-build override (see ProxyManager): -Duts.proxy.localPath=… or
     // $UTS_PROXY_LOCAL_PATH.
-    systemProperty("uts.proxy.localPath", …)
+    systemProperty(
+        "uts.proxy.localPath",
+        providers.systemProperty("uts.proxy.localPath")
+            .orElse(providers.environmentVariable("UTS_PROXY_LOCAL_PATH"))
+            .getOrElse(""),
+    )
 }
 
 tasks.register<Test>("runUtsUnitTests")        { filter { includeTestsMatching("io.ably.lib.uts.unit.*") } }