[AIT-1103] fix(liveobjects): Fix UTS unit tests

[sacOO7]

• Fixes https://ably.atlassian.net/browse/AIT-1103

Intent

Cross-checking our UTS unit suite against ably-js (the reference implementation the UTS specs are written against) surfaced two genuine spec-compliance bugs in the LiveObjects source — both places where ably-js passes the same spec test and ably-java did not. This PR fixes both at source level (validated against objects-features.md), un-gates their previously-skipped tests, and reconciles the suite's deviation records so they accurately reflect what is a bug, what is a shared gap, and what is an expected typed-SDK adaptation.

Source fixes

RTO23e — get() threw 90001 on a DETACHED channel instead of re-attaching

get() ran the full access-config check — which gates on channel state — before getRootAsync's ensure-active-channel procedure could run, so a DETACHED channel threw 90001 where the spec requires a re-attach.

• get() now uses a mode-only check (throwIfMissingObjectSubscribeMode, RTO23a) and delegates channel-state handling to ensureAttached (RTO23e / RTL33): DETACHED re-attaches and resolves; only FAILED rejects with 90001.
• The full access-config check remains on the access methods on/off/offAll (RTO25b), where the DETACHED gate is correct.

RTO20e / RTO20e1 — orphaned sync waiter could hang publishAndApply forever

The old design stored a single shared syncCompletionWaiter deferred that every startNewSync overwrote. Two deterministic failures followed (single-threaded scope notwithstanding — publishAndApply suspends across the ACK and sync waits, and state changes on the same scope while it is suspended):

1. Hang: the ordinary re-sync pair ATTACHED(HAS_OBJECTS) → OBJECT_SYNC calls startNewSync twice; a write awaiting the first deferred was orphaned by the second and never resumed — the user's set()/increment() future hung forever.
2. Missing 92008: a DETACHED racing the ACK completed-and-nulled the field without transitioning objects state, so the subsequent wait created a fresh deferred nobody would ever complete — hanging instead of failing with 92008 as RTO20e1 requires.

Replaced with an event-driven waiter set, mirroring ably-js publishAndApply:

• awaitSyncCompletion() — a tracked deferred + one-shot once(SYNCED) listener, so whichever sync ultimately completes resolves the wait (immune to re-sync orphaning).
• failSyncWaiters(error) — rejects all pending waiters with 92008 when the channel enters DETACHED/SUSPENDED/FAILED.
• Symmetric listener cleanup on both resolution paths (matching ably-js's cleanup()); ensureSynced gets the same off()-in-finally hygiene.

UTS suite changes

• Un-gated the now-passing RTO23e, RTO20e and RTO20e1 tests (previously env-gated as documented SDK bugs).
• Canonical serial helpers — adopted POOL_SERIAL / ackSerial / remoteSerial / belowAckSerial from the spec's new Canonical Constants section, replacing hand-rolled "t:N" literals (serials compare as strings; ad-hoc values silently sort wrong).
• Corrected counter fixtures (spec issue SI-1): residual count: 0 with the initial value on the createOp, so sync materialises count + createOp.count once instead of double-counting.
• RTPO19e2 fixture — single-object OBJECT_SYNC (root intentionally omitted and retained per RTO5c2a), matching the updated spec and ably-js test.
• RTO24c1 race fix (test-only) — the seed MAP_SET's own update could leak into the depth-2 listener as a spurious event; a control-listener barrier now quiesces the seed before the listener under test subscribes.
• Renamed LiveMapApiTest/LiveCounterApiTest → InternalLiveMapApiTest/InternalLiveCounterApiTest to match the renamed spec files (internal_live_map.md / internal_live_counter.md).

deviations.md

Restructured into four actionability groups so a reader can tell at a glance what needs fixing vs what is expected:

Group	Contents
1) Genuine SDK bugs — open	RTL13b, RTL13c, RTN16g2, RTN16f (realtime; annotated where tests are pending translation)
2) Shared gap — open in both SDKs	RTLC9h/RTLO4b4c1 (ably-js has the same documented deviation)
3) Expected — typed-SDK / language adaptations	16 entries: RTTS partitioning, compile-time guarantees, internal-wire visibility (not bugs)
4) Intentional deviation	RTO18d (spec point questioned; documented in both SDKs' deviation files)

The fixed RTO23e and RTO20e/e1 entries are removed (noted in the header), and every cited test name, UTS id and spec point was reconciled programmatically against the suite (208 methods / 210 @UTS ids / 110 spec tokens).

Cross-repo context

• The same investigation found and fixed an ably-js bug (RTO5c2a — root removed from the pool during sync, ably-js commit 6f432bff) and several ably-js test gaps (RTPO19e2/RTO24b2a/RTO24b2b un-skipped).
• Spec-side fixes (canonical serial helpers, SI-1/2/3 fixture corrections, wire-valid createOp builder contract) are in ably/specification commits 43c41af9 and b1c08c75.

Verification

• :uts:runUtsUnitTests liveobjects: 183 / 0 failures (RTO23e, RTO20e, RTO20e1, RTO24c1 included)
• runLiveObjectUnitTests: green
• checkWithCodenarc / checkstyleMain / checkstyleTest: clean

Summary by CodeRabbit

• Bug Fixes

  • Primitive path values are now returned through typed Instance wrappers.
  • Improved synchronization handling prevents hangs and correctly reports failures when channels become unavailable.
  • Refined access validation for object reads and subscriptions.

• Tests

  • Expanded coverage for path subscriptions, synchronization, object messages, typed values, and listener behavior.
  • Updated test fixtures and assertions for reliable object synchronization and acknowledgements.

• Documentation

  • Clarified path resolution, channel-state errors, object synchronization behavior, and documented SDK deviations.

[coderabbitai]

Walkthrough

The PR updates PathObject.instance() to wrap resolved primitives, refactors LiveObjects sync-wait failure handling, improves object test fixtures and serial helpers, and revises broad UTS coverage for paths, subscriptions, channel states, ACKs, and translated deviations.

Changes

LiveObjects behavior and contracts

Layer / File(s)	Summary
Instance wrapping contract lib/src/main/java/io/ably/lib/liveobjects/path/..., liveobjects/src/main/kotlin/io/ably/lib/liveobjects/path/...	Primitive path resolutions now produce Instance wrappers through toInstance; Javadocs and spec references describe the updated behavior.
Sync wait coordination liveobjects/src/main/kotlin/io/ably/lib/liveobjects/{DefaultRealtimeObject,ObjectsManager,ObjectsState,Helpers}.kt	get() validates only object subscription mode, while pending sync waiters are resumed on SYNCED and failed on unusable channel states.
Object test harness and wire fixtures uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/Helpers.kt	Canonical serial helpers, wire-message conversion, object IDs, ACK counts, connection settings, and OBJECT_SYNC setup were added or corrected.
Spec deviation mapping uts/src/test/kotlin/io/ably/lib/uts/{deviations.md,private_deviations.md}, .claude/skills/uts-to-kotlin/references/objects-mapping.md	Translated test mappings document current typed-SDK behavior, internal wire assertions, channel-state errors, and runnable test status.
Path, instance, and subscription coverage uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/{InstanceTest,InternalLive*,LiveObjectSubscribeTest,PathObject*,PublicObjectMessageTest}.kt	Tests update primitive instance assertions, listener quiescence, path depth/filtering, tombstones, raw operation markers, and compact JSON expectations.
RealtimeObject and value tests uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/{RealtimeObjectTest,ValueTypesTest}.kt	Tests use shared channel harnesses for sync transitions, channel failures, subscription behavior, ACK/echo ordering, garbage collection, and typed value mappings.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Test as RealtimeObjectTest
  participant Client as objectsClient
  participant Channel
  participant RealtimeObject
  Test->>Client: configure attach, sync, ACK, or failure
  Client->>Channel: emit protocol state
  Channel->>RealtimeObject: process OBJECT_SYNC or channel transition
  RealtimeObject-->>Test: resolve or fail get/write/subscription assertion

Loading

Possibly related PRs

• ably/ably-java#1213: Introduced the related path-based PathObject API and instance contract.
• ably/ably-java#1216: Added the LiveObjects implementation underlying get() and sync behavior.
• ably/ably-java#1223: Covers the related sync-wait coordination in the same core classes.

Suggested reviewers: ttypic

Poem

I’m a rabbit with tests in my paws,
Wrapping primitives without flaws.
Sync waiters wake or fail,
Serial helpers hop the trail,
While maps and counters cheer: “All clear!”

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is related to the PR but too generic; it doesn't convey the main LiveObjects behavior changes or test/documentation updates.	Use a more specific title, e.g. mention LiveObjects get()/publishAndApply fixes and UTS test updates.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 88.02% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/liveobjects-failing-uts-tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR brings ably-java LiveObjects closer to UTS spec compliance by fixing two runtime bugs in the LiveObjects engine (DETACHED get() handling and publishAndApply sync-wait correctness), then un-gating/updating the corresponding UTS unit tests and deviation records to match the now-correct behavior.

Changes:

• Fix RealtimeObject.get() to re-attach on DETACHED (and only reject on FAILED) by switching to a mode-only precheck and delegating channel-state handling to ensure-active-channel.
• Replace the single overwritten sync waiter used by publishAndApply with event-driven, tracked SYNCED waiters that cannot be orphaned and can be failed with 92008 on invalid channel states.
• Update UTS unit tests/helpers/fixtures (canonical serial helpers, corrected counter fixtures, race/quiescence barriers) and restructure deviations.md into actionability groups.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/ValueTypesTest.kt	Adds/adjusts value-type union assertions and typed-SDK deviation explanations (incl. new RTLCV3c adaptation).
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/RealtimeObjectTest.kt	Updates tests for RTO23e + RTO20e/e1 and introduces a reusable mock client builder for precondition/lifecycle cases.
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/PublicObjectMessageTest.kt	Aligns fixtures with spec marker semantics for OBJECT_DELETE and MAP_CLEAR retained markers.
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/PathObjectTest.kt	Refines typed-SDK mapping notes and restores/updates compact/value byte assertions and cycle handling checks.
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/PathObjectSubscribeTest.kt	Adjusts depth semantics, serial ordering, and adds quiescence barriers to avoid negative-assertion flakiness.
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/PathObjectMutationsTest.kt	Clarifies typed-SDK write mapping; mostly naming/comment tightening.
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/LiveObjectSubscribeTest.kt	Adds quiescence barriers and documents/env-gates shared-gap noop behavior.
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/InternalLiveMapApiTest.kt	Renames to match spec file and reintroduces bytes-set test while keeping wire-shape deviations as observable-effect assertions.
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/InternalLiveCounterApiTest.kt	Renames to match spec file and tightens documentation around internal-wire reflection assertions.
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/InstanceTest.kt	Updates subscription/unsubscribe quiescence patterns and adapts assertions to match typed-SDK instance semantics.
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/Helpers.kt	Adds canonical serial helpers, fixes JSON wire encoding, converts wire JSON into internal WireObjectMessage via reflection, and corrects pool counter fixtures.
uts/src/test/kotlin/io/ably/lib/uts/deviations.md	Re-groups deviations by actionability; removes fixed entries and adds a shared-gap entry for missing-number COUNTER_INC noop.
liveobjects/src/main/kotlin/io/ably/lib/liveobjects/ObjectsState.kt	Implements tracked SYNCED waiters + waiter-failing to prevent publishAndApply hangs across re-syncs.
liveobjects/src/main/kotlin/io/ably/lib/liveobjects/ObjectsManager.kt	Removes the overwritten shared deferred and uses the new tracked SYNCED waiter mechanism.
liveobjects/src/main/kotlin/io/ably/lib/liveobjects/Helpers.kt	Adds a mode-only access check for get() to avoid pre-empting DETACHED reattach behavior.
liveobjects/src/main/kotlin/io/ably/lib/liveobjects/DefaultRealtimeObject.kt	Switches get() to mode-only validation and routes channel-state failure to the new sync-waiter failing mechanism.
.claude/skills/uts-to-kotlin/references/objects-mapping.md	Updates mapping guidance to reflect the corrected get() behavior and canonical serial helpers usage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ttypic]

LGTM

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@liveobjects/src/main/kotlin/io/ably/lib/liveobjects/ObjectsState.kt`:
- Around line 67-72: The local deferred used by ensureSynced() is not registered
in pendingSyncWaiters, so failSyncWaiters() cannot release it on channel
failure. Update ensureSynced() and its get() waiting path to register the
deferred in pendingSyncWaiters, ensuring DETACHED, SUSPENDED, or FAILED states
fail through the existing 92008 handling used by publishAndApply.

In `@uts/src/test/kotlin/io/ably/lib/uts/deviations.md`:
- Line 87: Update the heading for RTLC9h / RTLC16 / RTLO4b4c1 in deviations.md
to use the hyphenated term “no-ops” instead of “noops,” preserving the rest of
the wording unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0a258fbc-87fc-45d7-8b2e-20ae7d1e5cfe

📥 Commits

Reviewing files that changed from the base of the PR and between 0f0075a and 30c1821.

📒 Files selected for processing (27)

• .claude/skills/uts-to-kotlin/references/objects-mapping.md
• lib/src/main/java/io/ably/lib/liveobjects/path/PathObject.java
• lib/src/main/java/io/ably/lib/liveobjects/path/types/BinaryPathObject.java
• lib/src/main/java/io/ably/lib/liveobjects/path/types/BooleanPathObject.java
• lib/src/main/java/io/ably/lib/liveobjects/path/types/JsonArrayPathObject.java
• lib/src/main/java/io/ably/lib/liveobjects/path/types/JsonObjectPathObject.java
• lib/src/main/java/io/ably/lib/liveobjects/path/types/NumberPathObject.java
• lib/src/main/java/io/ably/lib/liveobjects/path/types/StringPathObject.java
• liveobjects/src/main/kotlin/io/ably/lib/liveobjects/DefaultRealtimeObject.kt
• liveobjects/src/main/kotlin/io/ably/lib/liveobjects/Helpers.kt
• liveobjects/src/main/kotlin/io/ably/lib/liveobjects/ObjectsManager.kt
• liveobjects/src/main/kotlin/io/ably/lib/liveobjects/ObjectsState.kt
• liveobjects/src/main/kotlin/io/ably/lib/liveobjects/instance/DefaultInstance.kt
• liveobjects/src/main/kotlin/io/ably/lib/liveobjects/path/DefaultPathObject.kt
• uts/src/test/kotlin/io/ably/lib/uts/deviations.md
• uts/src/test/kotlin/io/ably/lib/uts/private_deviations.md
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/Helpers.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/InstanceTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/InternalLiveCounterApiTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/InternalLiveMapApiTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/LiveObjectSubscribeTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/PathObjectMutationsTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/PathObjectSubscribeTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/PathObjectTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/PublicObjectMessageTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/RealtimeObjectTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/ValueTypesTest.kt