Add UTS test specs for LiveObjects path-based API

uts/README.md

@@ -28,14 +28,13 @@ uts/
 │   │   ├── connection/                # RTN — connection management
 │   │   └── presence/                  # RTP — realtime presence
 │   └── integration/                   # Realtime integration tests
-│       ├── helpers/
-│       │   └── proxy.md               # Proxy infrastructure spec
 │       ├── proxy/                     # Proxy-based fault injection tests
 │       └── *.md                       # Direct sandbox tests
 ├── docs/                              # Guides and reference
 │   ├── writing-test-specs.md          # How to write UTS specs
 │   ├── writing-derived-tests.md       # How to translate specs into SDK tests
 │   ├── integration-testing.md         # Integration testing policy
+│   ├── proxy.md                       # Proxy infrastructure spec (cross-module)
 │   └── completion-status.md           # Spec coverage matrix
 └── README.md                          # This file
 ```
@@ -101,4 +100,4 @@ See [docs/writing-test-specs.md](docs/writing-test-specs.md) for the full pseudo
 
 The programmable proxy for integration testing lives in a separate repository: [ably/uts-proxy](https://github.com/ably/uts-proxy). It sits between the SDK and the Ably sandbox, transparently forwarding traffic while allowing rule-based fault injection.
 
-See `realtime/integration/helpers/proxy.md` for the proxy infrastructure specification used by test specs in this repository.
+See `uts/docs/proxy.md` for the proxy infrastructure specification used by test specs in this repository.

uts/docs/integration-testing.md

@@ -99,8 +99,6 @@ realtime/
     presence/
       presence_lifecycle_test.md
       ...
-    helpers/
-      proxy.md                             # Proxy infrastructure spec
     proxy/                                 # Proxy-based tests (sandbox + proxy)
       connection_open_failures.md
       connection_resume.md
@@ -151,13 +149,12 @@ AFTER ALL TESTS:
 
 ### Proxy Setup (integration-proxy only)
 
-Proxy tests additionally set up a proxy session per test or group of tests. See `realtime/integration/helpers/proxy.md` for the proxy infrastructure API.
+Proxy tests additionally set up a proxy session per test or group of tests. See `uts/docs/proxy.md` for the proxy infrastructure API.
 
 ```pseudo
 BEFORE EACH TEST:
   session = create_proxy_session(
     endpoint: "nonprod:sandbox",
-    port: allocated_port,
     rules: [ ...initial rules... ]
   )
 
@@ -228,6 +225,12 @@ Guidelines:
 
 The goal is: every await in the test is bounded, and the suite timeout is generous enough that it only fires if something truly unexpected happens. When a test fails, the error should say *what* timed out, not just "suite timeout exceeded."
 
+**All timeouts are wall-clock time.** Every `WITH timeout`, `poll_until` and `WAIT` in an
+integration spec measures real elapsed time — the test is waiting on a real server over a real
+network. Derived tests in frameworks that virtualise time by default must run these waits
+against the real clock; see the *Integration timeouts are wall-clock* section in
+`writing-derived-tests.md` for the failure mode and recommended helpers.
+
 ### Avoiding Flaky Tests
 
 - Use polling with timeouts instead of fixed waits (see `README.md` polling conventions)
@@ -296,6 +299,10 @@ The following integration test specs are annotated with `## Protocol Variants`:
 - `realtime/integration/mutable_messages_test.md`
 - `realtime/integration/delta_decoding_test.md`
 
+**LiveObjects:**
+- `objects/integration/objects_lifecycle_test.md`
+- `objects/integration/objects_sync_test.md`
+
 ## Writing Proxy Tests
 
 The proxy mediates between the SDK and the real Ably server. It is not a mock server. Tests should be written to rely on actual server responses as much as possible, with the proxy intervening only where necessary to create the specific fault or error condition under test.

uts/realtime/integration/helpers/proxy.md → uts/docs/proxy.md

@@ -20,7 +20,6 @@ Proxy integration tests use this to verify fault-handling behaviour against the
 # 1. Create a proxy session with rules
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
   rules: [ ...rules... ]
 )
 
@@ -58,7 +57,7 @@ session.close()
 interface ProxySession:
   session_id: String
   proxy_host: String     # Always "localhost"
-  proxy_port: Int        # Assigned from port pool
+  proxy_port: Int        # Auto-assigned by proxy, or explicit if specified
 
   add_rules(rules: List<Rule>, position?: "append"|"prepend")
   trigger_action(action: ActionRequest)
@@ -67,7 +66,7 @@ interface ProxySession:
 
 function create_proxy_session(
   endpoint: String,       # e.g. "nonprod:sandbox" → resolves to sandbox.realtime.ably-nonprod.net
-  port: Int,
+  port?: Int,             # Optional; proxy auto-assigns a free port if omitted
   rules?: List<Rule>,
   timeoutMs?: Int         # Session auto-cleanup timeout (default 30000)
 ): ProxySession
@@ -113,6 +112,14 @@ Rules are evaluated in order. First matching rule wins. Unmatched traffic passes
 
 **`count`**: 1-based occurrence counter. `count: 2` matches only the 2nd occurrence.
 
+**`action`** (frame matches): must be a **string** — either a protocol action *name*
+(e.g. `"ATTACHED"`) or a *numeric string* (e.g. `"20"`). A JSON number is rejected at
+session creation with HTTP 400 (`cannot unmarshal number into Go struct field
+MatchConfig.match.action of type string`). Note: uts-proxy v0.3.0 resolves action
+*names* only up to `AUTH` (17) — an unresolvable name (e.g. `"OBJECT_SYNC"`) makes the
+rule silently never match, so use numeric strings for `OBJECT` (`"19"`),
+`OBJECT_SYNC` (`"20"`) and `ANNOTATION` (`"21"`) until the proxy's name table is extended.
+
 ### Actions
 
 ```json
@@ -203,6 +210,9 @@ ASSERT attach_frames.length == 1
 | MESSAGE | 15 | Both |
 | SYNC | 16 | Server → Client |
 | AUTH | 17 | Client → Server |
+| OBJECT | 19 | Both |
+| OBJECT_SYNC | 20 | Server → Client |
+| ANNOTATION | 21 | Both |
 
 ## SDK ClientOptions for Proxy Tests
 
@@ -231,3 +241,6 @@ ClientOptions(
 7. Timeouts are generous (10-30s) since real network is involved
 8. Each test file provisions a sandbox app in `BEFORE ALL TESTS` and cleans up in `AFTER ALL TESTS`
 9. Each test creates its own proxy session and cleans it up after
+10. All `WITH timeout` / `poll_until` / `WAIT` durations are **wall-clock (real) time** — see
+    the *Integration timeouts are wall-clock* section in `writing-derived-tests.md` for
+    the virtual-time trap in derived tests

uts/docs/writing-derived-tests.md

@@ -268,6 +268,27 @@ const timer = setTimeout(() => reject(new Error('Timed out')), 5000);
 connection.once('connected', () => { clearTimeout(timer); resolve(); });
 ```
 
+### Integration timeouts are wall-clock (beware virtual-time frameworks)
+
+The rule above is inverted for **integration and proxy tests**: every `WITH timeout`,
+`poll_until` and `WAIT` in an integration spec is **wall-clock (real) time**, because the test
+is waiting on a real server or proxy over a real network.
+
+This is a trap in test frameworks that virtualise time by default. For example,
+kotlinx-coroutines' `runTest` runs the test body on a virtual clock: a bare `withTimeout(15s)`
+wrapping a real network await measures *virtual* time, which fast-forwards the moment the test
+coroutine idles — the timeout fires almost instantly, long before the server can respond, with
+a misleading "Timed out after 15s" error. The same applies to a bare `delay()`, which skips
+instead of waiting.
+
+Derived integration tests in such frameworks must run their waits against the real clock —
+e.g. dispatch onto a real-thread dispatcher before applying the timeout
+(`withContext(Dispatchers.Default.limitedParallelism(1)) { withTimeout(...) { ... } }` in
+Kotlin), or use the framework's escape hatch for real time. Define shared helpers
+(`awaitState`, `pollUntil`, `withRealTimeout`, ...) that encapsulate this once, and use them for
+every wait in integration test bodies. Unit tests are unaffected — there, fake/virtual timers
+remain the preferred mechanism.
+
 ### Cleanup with afterEach
 
 Always restore mocks in `afterEach`, not just at the end of each test. If a test throws before its cleanup code, the next test inherits dirty state. Use the SDK's mock restoration mechanism (e.g. `restoreAll()`) in an `afterEach` hook.

uts/docs/writing-test-specs.md

@@ -21,7 +21,7 @@ This guide provides comprehensive guidance for writing portable test specificati
 - Run against Ably Sandbox through a programmable proxy ([ably/uts-proxy](https://github.com/ably/uts-proxy))
 - Proxy transparently forwards traffic but can inject faults via rules
 - Use for testing fault behaviour: connection failures, token renewal under errors, heartbeat starvation, channel error injection
-- See `realtime/integration/helpers/proxy.md` for the full proxy infrastructure spec
+- See `uts/docs/proxy.md` for the full proxy infrastructure spec
 
 ## Test IDs
 
@@ -296,7 +296,7 @@ mock_ws.active_connection.simulate_disconnect()
 
 ## Proxy Integration Tests
 
-For detailed proxy infrastructure documentation, see `realtime/integration/helpers/proxy.md`.
+For detailed proxy infrastructure documentation, see `uts/docs/proxy.md`.
 
 ### When to Use Proxy Tests
 
@@ -317,7 +317,7 @@ Spec points: `RTN14a`, `RTN14b`, ...
 Proxy integration test against Ably Sandbox endpoint
 
 ## Proxy Infrastructure
-See `realtime/integration/helpers/proxy.md` for proxy infrastructure specification.
+See `uts/docs/proxy.md` for proxy infrastructure specification.
 
 ## Corresponding Unit Tests
 - `realtime/unit/connection/connection_failures_test.md` — RTN15a, RTN15b
@@ -344,7 +344,6 @@ Tests that [behaviour] when the proxy injects [fault].
 ```pseudo
 session = create_proxy_session(
   target: TargetConfig(realtimeHost: "sandbox.realtime.ably-nonprod.net", restHost: "sandbox.realtime.ably-nonprod.net"),
-  port: allocated_port,
   rules: [{
     "match": { ... },
     "action": { ... },
@@ -588,6 +587,10 @@ This means implementations should:
 - Otherwise wait for state change events with timeout
 - Fail if timeout expires
 
+In **integration and proxy** specs these timeouts are **wall-clock time** (the test waits on a
+real server — see the *Timeout Strategy* section in `docs/integration-testing.md`); in unit specs they may be
+realised with fake/virtual timers.
+
 ## Timer Mocking
 
 Tests verifying timeout behavior should use timer mocking where practical to avoid slow tests.
@@ -1026,8 +1029,6 @@ realtime/
       connection_open_failures_test.md
       ...
   integration/
-    helpers/
-      proxy.md                # Proxy infrastructure spec
     proxy/
       connection_open_failures.md   # RTN14 tests via proxy
       connection_resume.md          # RTN15 tests via proxy