feat(liveobjects): implement remaining path-based API — parent references, event bubbling etc

[sacOO7]

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

Summary

Completes the path-based LiveObjects public API in the liveobjects Kotlin module. The sync/CRDT engine and serialization layers landed earlier on the base branch; this PR fills in everything between them and the public interfaces: value resolution, reads, writes, identity-bound instances, parent references, and subscription event bubbling. ably-js liveobjects plugin is the source of truth throughout, with spec points (objects-features.md, plus the unmerged typed-SDK points from ably/specification#491) anchored inline as code comments.

What was missing before

The module had a complete sync engine but the path/instance layers were skeletons: ResolvedValue wrapped the wrong types (public blueprints instead of the internal CRDT objects), every read/write/subscribe method was a TODO(), and update events carried no source message, no tombstone signal and no path information.

Changes

Internal graph bridge

• ResolvedValue is now a sealed interface over the internal graph: MapRef(InternalLiveMap) / CounterRef(InternalLiveCounter) / Leaf(WireObjectData), resolved per call via LiveMapEntry.getResolvedValue() (tombstone- and dangling-ref-aware, RTLM5d2).
• PathSegments handles dot-delimited path ↔ segment conversion with escape-aware parsing (RTPO4, RTPO6). Deviation from ably-js: join escapes backslashes as well as dots, because here the joined string is the storage and gets re-parsed on every resolution (ably-js stores segment arrays and only renders the escaped string). Without this, a key ending in \ collides with the escaped-dot separator and breaks lookups/subscriptions.

Typed update model

• ObjectUpdate is a sealed class (NoOp / MapUpdate / CounterUpdate) carrying the source WireObjectMessage and a tombstone flag (RTLO4b4). Both managers thread the message through every apply/merge/diff path (RTLM6h, RTLC6h, RTLM23c).

Parent references & event bubbling

• Every object tracks its parents (parentReferences, keyed by parent objectId per RTLO3f), maintained at all mutation points and rebuilt wholesale after sync (RTO5c10, ordered before the RTO5c7 notifications).
• getFullPaths() computes all simple paths from root with cycle safety (RTLO4f); notifyUpdated fans out to instance listeners, then bubbles to path subscribers via PathObjectSubscriptionRegister (RTO24: prefix + depth coverage, most-preferred candidate path, at-most-once per subscription, per-listener error isolation), then tears down instance listeners on tombstone (RTLO4b4c3).
• Sync-time messages are filtered from public events (operation == null), and surfaced messages are converted once via toPublicMessage (PAOM3).

Reads, writes and instances

• RealtimeObject#get() returns the root LiveMapPathObject after attach + sync (RTO23), bridged from coroutines with sequentialScope.future {}.
• All path reads re-resolve on every call (RTPO3) — typed value()s, map iteration, compactJson() with cycle markers (RTPO13/14).
• Writes evaluate value-type blueprints recursively (LiveMapValueType/LiveCounterValueType, RTLMV4/RTLCV4): nested create messages first, own MAP_CREATE last, published together with the MAP_SET in a single protocol message (RTLM20h1).
• All 8 Instance types are value-bound (RTINS2a): live map/counter instances delegate to the internal objects; primitives capture the extracted value (binary decoded once, defensively copied out).

Fix found during cross-validation against ably-js history

• handleStateChange(ATTACHED) now clears buffered operations (RTO4d) and starts a new sync unconditionally (RTO4c). The previous conditional was a port of pre-e280bff1 ably-js code that upstream has since removed.

Testing & validation

• New PathSegmentsTest covers the stored-vs-supplied path invariants and the backslash round-trip regression.
• runUnitTests, runLiveObjectsUnitTests, checkWithCodenarc, checkstyleMain/Test all green; zero TODOs remain in the module.
• Every spec anchor in the module (683 unique points) was verified against objects-features.md / spec PR README: add a note about the push example/test app #491; behavioral markers (boundary comparisons, error codes, skip predicates, message ordering) were cross-checked against ably-js.
• Proguard: no new reflective entry points; blueprint constructor signatures ((Number) / (Map)) unchanged, existing keep rules remain valid.

Notes for reviewers

• UTS LiveObjects suites are re-enabled in uts/build.gradle.kts but failures there are pending triage in a follow-up — check the spec anchor before assuming an engine bug.
• RTTS/typed-SDK spec points reference the unmerged Add typed-SDK LiveObjects API spec section (RTTS1-RTTS10) specification#491; anchors should be re-verified once it merges.
• Known deliberate deviations from ably-js (each documented at the code site): empty map keys are rejected with 40003 (ably-js accepts them), instance-layer entries() skips dangling references (RTLM11d3a) while keys() does not, and the backslash escaping described above.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 84b7aaa6-ddf4-4fa7-a9dd-6ed5303ba145

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/liveobjects-remaining-kotlin-implementation

---

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.}