uts: add nanoTime support to Clock and update usages for consistency

- moved uts infrastructure related files into `uts.infra`
- updated skill
- simplify code in constructor

Author: ttypic

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

@@ -5,7 +5,46 @@ allowed-tools: Bash, Read, Edit, Write
 
 Translate the UTS pseudocode test spec at `$ARGUMENTS` into a runnable Kotlin test in the `uts` module.
 
-Reference: [Writing Derived Tests](https://github.com/ably/specification/blob/main/uts/docs/writing-derived-tests.md)
+Reference: [Writing Derived Tests](https://raw.githubusercontent.com/ably/specification/refs/heads/main/uts/docs/writing-derived-tests.md)
+
+---
+
+## Step 0 — Validate arguments
+
+**If `$ARGUMENTS` is empty or blank**, stop immediately and tell the user:
+
+```
+Usage: /uts-to-kotlin <path-to-spec-file>
+
+Example:
+  /uts-to-kotlin lib/src/spec/uts/test/realtime/unit/connection/connection_state_machine_test.md
+
+Please re-run the command with the path to a UTS pseudocode spec file.
+```
+
+Do not proceed to Step 1.
+
+**If `$ARGUMENTS` is provided but does not end in `.md`**, stop and tell the user:
+
+```
+Error: "<value>" does not look like a spec file path (expected a .md file).
+
+Usage: /uts-to-kotlin <path-to-spec-file>
+```
+
+Do not proceed to Step 1.
+
+**If `$ARGUMENTS` ends in `.md` but the file does not exist** (check with `test -f "$ARGUMENTS"`), stop and tell the user:
+
+```
+Error: file not found: "<value>"
+
+Check the path and try again.
+```
+
+Do not proceed to Step 1.
+
+Only continue to Step 1 once the file is confirmed to exist.
 
 ---
 
@@ -37,19 +76,7 @@ Package: derived from the output path under `kotlin/`.
 
 ## Step 3 — Read infrastructure files
 
-Read ALL of these before generating any code (you need exact method signatures):
-
-```
-uts/src/test/kotlin/io/ably/lib/ClientFactories.kt
-uts/src/test/kotlin/io/ably/lib/test/mock/MockWebSocket.kt
-uts/src/test/kotlin/io/ably/lib/test/mock/MockHttpClient.kt
-uts/src/test/kotlin/io/ably/lib/test/mock/PendingRequest.kt
-uts/src/test/kotlin/io/ably/lib/test/mock/PendingConnection.kt
-uts/src/test/kotlin/io/ably/lib/test/mock/FakeClock.kt
-uts/src/test/kotlin/io/ably/lib/test/mock/MockEvent.kt
-```
-
----
+Read ALL of files in `uts/src/test/kotlin/io/ably/lib/uts/infra` before generating any code (you need exact method signatures).
 
 ## Step 4 — Generate the Kotlin test file
 
@@ -332,7 +359,7 @@ Test fails
 @Test
 fun `RSA4c2 - callback error connecting disconnected`() = runTest {
     // DEVIATION: see deviations.md
-    if (System.getenv("RUN_DEVIATIONS") != null) return@runTest
+    if (System.getenv("RUN_DEVIATIONS") == null) return@runTest
 
     // ... spec-correct setup and assertions ...
 }
@@ -354,3 +381,39 @@ Append to `uts/src/test/kotlin/io/ably/lib/deviations.md`. Each entry needs:
 2. What the spec says
 3. What the SDK does
 4. Which test is affected and how it was adapted
+
+---
+
+## Step 7 — Review generated output against the spec
+
+Re-read the original spec file and the generated Kotlin test file side-by-side and check every item below. Fix anything that fails a check before declaring the task done.
+
+### Coverage check — every test case is present
+
+For each test case ID in the spec:
+- [ ] A `@Test` method exists with that ID in its `@UTS` KDoc tag
+- [ ] The method name contains the spec ID and a meaningful description
+
+Flag any spec test case that has no corresponding `@Test` method as **missing** and implement it.
+
+### Assertion completeness — every `ASSERT` / `AWAIT` is translated
+
+For each `ASSERT`, `AWAIT`, or observable outcome stated in the spec pseudocode:
+- [ ] There is a direct Kotlin assertion (`assertEquals`, `assertNotNull`, `assertNull`, `assertIs`, `assertTrue`, `assertFailsWith`, etc.) or an `awaitState` / `awaitChannelState` call covering it
+- [ ] No spec assertion has been silently dropped or weakened (e.g. replaced with a comment)
+
+### Setup fidelity — preconditions match the spec
+
+For each test case, verify:
+- [ ] Client options (`autoConnect`, `recover`, timeouts, etc.) match the spec's `ClientOptions`
+- [ ] Mock responses (success / refused / timeout / DNS error / custom messages) match the spec's prescribed network behaviour
+- [ ] Timer setup (`enableFakeTimers`, `fakeClock.advance(...)`) matches every `enable_fake_timers` / `ADVANCE_TIME` in the spec
+- [ ] Channel operations (attach, detach, publish) are performed in the order the spec requires
+
+### Deviation honesty
+
+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 `uts/src/test/kotlin/io/ably/lib/deviations.md`
+
+If you find gaps during this review, fix them and re-run Steps 5–6 before finishing.

lib/src/main/java/io/ably/lib/realtime/ChannelBase.java

@@ -50,7 +50,7 @@
 import io.ably.lib.util.EventEmitter;
 import io.ably.lib.util.Listeners;
 import io.ably.lib.util.Log;
-import io.ably.lib.util.NamedTimer;
+import io.ably.lib.util.AblyTimer;
 import io.ably.lib.util.ReconnectionStrategy;
 import io.ably.lib.util.StringUtils;
 import io.ably.lib.util.SystemClock;
@@ -510,18 +510,18 @@ private void setFailed(ErrorInfo reason) {
     }
 
     /* Timer for attach operation */
-    private NamedTimer attachTimer;
+    private AblyTimer attachTimer;
 
     /* Timer for reattaching if attach failed */
-    private NamedTimer reattachTimer;
+    private AblyTimer reattachTimer;
 
     /**
      * Cancel attach/reattach timers
      */
     synchronized private void clearAttachTimers() {
-        NamedTimer[] timers = new NamedTimer[]{attachTimer, reattachTimer};
+        AblyTimer[] timers = new AblyTimer[]{attachTimer, reattachTimer};
         attachTimer = reattachTimer = null;
-        for (NamedTimer t: timers) {
+        for (AblyTimer t: timers) {
             if (t != null) {
                 t.cancel();
             }
@@ -538,7 +538,7 @@ private void attachWithTimeout(final CompletionListener listener) throws AblyExc
      */
     synchronized private void attachWithTimeout(final boolean forceReattach, final CompletionListener listener, ErrorInfo reattachmentReason) {
         checkChannelIsNotReleased();
-        NamedTimer currentAttachTimer;
+        AblyTimer currentAttachTimer;
         try {
             currentAttachTimer = clock.newTimer("attach-timer");
         } catch(Throwable t) {
@@ -572,7 +572,7 @@ public void onError(ErrorInfo reason) {
             return;
         }
 
-        final NamedTimer inProgressTimer = currentAttachTimer;
+        final AblyTimer inProgressTimer = currentAttachTimer;
         attachTimer.schedule(
                 new TimerTask() {
                     @Override
@@ -602,7 +602,7 @@ private void checkChannelIsNotReleased() {
      * try to attach the channel
      */
     synchronized private void reattachAfterTimeout() {
-        NamedTimer currentReattachTimer;
+        AblyTimer currentReattachTimer;
         try {
             currentReattachTimer = clock.newTimer("reattach-timer");
         } catch(Throwable t) {
@@ -614,7 +614,7 @@ synchronized private void reattachAfterTimeout() {
         this.retryAttempt++;
         int retryDelay = ReconnectionStrategy.getRetryTime(ably.options.channelRetryTimeout, retryAttempt);
 
-        final NamedTimer inProgressTimer = currentReattachTimer;
+        final AblyTimer inProgressTimer = currentReattachTimer;
         reattachTimer.schedule(new TimerTask() {
             @Override
             public void run() {
@@ -641,7 +641,7 @@ public void run() {
      */
     synchronized private void detachWithTimeout(final CompletionListener listener) {
         final ChannelState originalState = state;
-        NamedTimer currentDetachTimer;
+        AblyTimer currentDetachTimer;
         try {
             currentDetachTimer = released.get() ? null : clock.newTimer("detach-timer");
         } catch(Throwable t) {
@@ -677,7 +677,7 @@ public void onError(ErrorInfo reason) {
             return;
         }
 
-        final NamedTimer inProgressTimer = currentDetachTimer;
+        final AblyTimer inProgressTimer = currentDetachTimer;
         attachTimer.schedule(new TimerTask() {
             @Override
             public void run() {

lib/src/main/java/io/ably/lib/rest/Auth.java

@@ -923,7 +923,7 @@ else if(!request.keyName.equals(keyName))
         if(request.timestamp == 0) {
             if(options.queryTime) {
                 long oldNanoTimeDelta = nanoTimeDelta;
-                long currentNanoTimeDelta = clock.currentTimeMillis() - System.nanoTime()/(1000*1000);
+                long currentNanoTimeDelta = clock.currentTimeMillis() - clock.nanoTime()/(1000*1000);
 
                 if (timeDelta != Long.MAX_VALUE) {
                     /* system time changed by more than 500ms since last time? */
@@ -1053,7 +1053,7 @@ public void onAuthError(ErrorInfo err) {
     Auth(AblyBase ably, ClientOptions options) throws AblyException {
         this.ably = ably;
         this.clock = SystemClock.clockFrom(options);
-        this.nanoTimeDelta = clock.currentTimeMillis() - System.nanoTime()/(1000*1000);
+        this.nanoTimeDelta = clock.currentTimeMillis() - clock.nanoTime()/(1000*1000);
         authOptions = options;
         tokenParams = options.defaultTokenParams != null ?
                 options.defaultTokenParams : new TokenParams();

lib/src/main/java/io/ably/lib/transport/WebSocketTransport.java

@@ -17,7 +17,7 @@
 import io.ably.lib.util.Clock;
 import io.ably.lib.util.ClientOptionsUtils;
 import io.ably.lib.util.Log;
-import io.ably.lib.util.NamedTimer;
+import io.ably.lib.util.AblyTimer;
 import io.ably.lib.util.SystemClock;
 import io.ably.lib.util.TimerInstance;
 
@@ -261,7 +261,7 @@ class WebSocketHandler implements WebSocketListener {
          * WsClient private members
          ***************************/
 
-        private final NamedTimer timer = clock.newTimer("activity-timer");
+        private final AblyTimer timer = clock.newTimer("activity-timer");
         private volatile TimerInstance activityTimerHandle = null;
         private volatile long lastActivityTime;
 

…in/java/io/ably/lib/util/NamedTimer.java …ain/java/io/ably/lib/util/AblyTimer.javalib/src/main/java/io/ably/lib/util/NamedTimer.java renamed to lib/src/main/java/io/ably/lib/util/AblyTimer.java lib/src/main/java/io/ably/lib/util/NamedTimer.java renamed to lib/src/main/java/io/ably/lib/util/AblyTimer.java

@@ -2,7 +2,7 @@
 
 import java.util.TimerTask;
 
-public interface NamedTimer {
+public interface AblyTimer {
     TimerInstance schedule(TimerTask task, long delayMs);
     void cancel();
 }

lib/src/main/java/io/ably/lib/util/Clock.java

@@ -19,15 +19,23 @@ public interface Clock {
     long currentTimeMillis();
 
     /**
-     * Creates a new {@link NamedTimer} backed by this clock.
+     * Returns the current wall-clock time in nanoseconds since the Unix epoch
+     * (1 January 1970 00:00:00 UTC), analogous to {@link System#nanoTime()}.
+     *
+     * @return current time in nanoseconds
+     */
+    long nanoTime();
+
+    /**
+     * Creates a new {@link AblyTimer} backed by this clock.
      *
      * <p>The name is used for diagnostic and logging purposes (e.g. as the underlying
      * {@link java.util.Timer} thread name).
      *
      * @param name a human-readable label for the timer; must not be {@code null}
-     * @return a new {@link NamedTimer} instance ready to schedule tasks
+     * @return a new {@link AblyTimer} instance ready to schedule tasks
      */
-    NamedTimer newTimer(String name);
+    AblyTimer newTimer(String name);
 
     /**
      * Causes the current thread to wait until either another thread calls

lib/src/main/java/io/ably/lib/util/SystemClock.java

@@ -15,9 +15,14 @@ public long currentTimeMillis() {
     }
 
     @Override
-    public NamedTimer newTimer(String name) {
+    public long nanoTime() {
+        return System.nanoTime();
+    }
+
+    @Override
+    public AblyTimer newTimer(String name) {
         Timer jTimer = new Timer(name, true);
-        return new NamedTimer() {
+        return new AblyTimer() {
             @Override
             public TimerInstance schedule(TimerTask task, long delayMs) {
                 jTimer.schedule(task, delayMs);

liveobjects/src/main/kotlin/io/ably/lib/objects/DefaultRealtimeObjects.kt

@@ -13,7 +13,9 @@ import io.ably.lib.realtime.ChannelState
 import io.ably.lib.types.AblyException
 import io.ably.lib.types.ProtocolMessage
 import io.ably.lib.types.PublishResult
+import io.ably.lib.util.Clock
 import io.ably.lib.util.Log
+import io.ably.lib.util.SystemClock
 import kotlinx.coroutines.*
 import kotlinx.coroutines.channels.Channel.Factory.UNLIMITED
 import kotlinx.coroutines.flow.MutableSharedFlow
@@ -361,3 +363,10 @@ internal class DefaultRealtimeObjects(internal val channelName: String, internal
     asyncScope.cancel(disposeReason) // cancel all ongoing callbacks
   }
 }
+
+/**
+ * Provides the default Clock instance for the DefaultRealtimeObjects.
+ * This Clock is derived from the system clock, utilizing the client options
+ * from the adapter configuration.
+ */
+internal val DefaultRealtimeObjects.clock get(): Clock = SystemClock.clockFrom(adapter.clientOptions)

liveobjects/src/main/kotlin/io/ably/lib/objects/type/livecounter/DefaultLiveCounter.kt

@@ -23,7 +23,7 @@ import kotlinx.coroutines.runBlocking
 internal class DefaultLiveCounter private constructor(
   objectId: String,
   private val realtimeObjects: DefaultRealtimeObjects,
-) : LiveCounter, BaseRealtimeObject(objectId, ObjectType.Counter, SystemClock.clockFrom(realtimeObjects.adapter.clientOptions)) {
+) : LiveCounter, BaseRealtimeObject(objectId, ObjectType.Counter, realtimeObjects.clock) {
 
   override val tag = "LiveCounter"
 

liveobjects/src/main/kotlin/io/ably/lib/objects/type/livemap/DefaultLiveMap.kt

@@ -30,7 +30,7 @@ internal class DefaultLiveMap private constructor(
   objectId: String,
   private val realtimeObjects: DefaultRealtimeObjects,
   internal val semantics: ObjectsMapSemantics = ObjectsMapSemantics.LWW
-) : LiveMap, BaseRealtimeObject(objectId, ObjectType.Map, SystemClock.clockFrom(realtimeObjects.adapter.clientOptions)) {
+) : LiveMap, BaseRealtimeObject(objectId, ObjectType.Map, realtimeObjects.clock) {
 
   override val tag = "LiveMap"