docs(liveobjects): updated path-based LiveObjects API proposal (v2)

[sacOO7]

Summary

Adds path-base-api-proposal-updated.md at the repo root — a v2 design proposal for the path-based LiveObjects public API in ably-java. It supersedes PR #1190 by folding in the review feedback (primarily from @sacOO7) and reconciling the design against the actual source tree.

This is a docs-only change — no source files are modified.

Why a new proposal

PR #1190 sketched a path-based API but the review surfaced design
questions that materially change the shape:

• PathObject should not be statically typed (types at a path are dynamic); strong typing belongs on instances.
• The root should be a dedicated RootPathObject — it's the only position whose type is fixed.
• LiveMap / LiveCounter are spec-internal names; the path API should expose LiveMapInstance / LiveCounterInstance.
• An explicit LivePrimitive type is needed.
• compact() can't return an anonymous object in Java; needs a typed shape (Map<String, LiveValue> + a separate JSON-safe variant).
• MessageOptions doesn't exist in ably-js — drop it.
• LiveListPathObject shouldn't exist (no LiveList in the spec).
• channel.object().get() reads better than channel.getObject().get().

What's in the proposal

• Background & problem statement (vs. the existing RealtimeObjects API) and goals/non-goals.
• Review-feedback decisions (D1–D11) with a per-comment mapping in Appendix A.
• Updated Java/Kotlin API — PathObject, RootPathObject, LiveValue / LiveInstance / LiveMapInstance /LiveCounterInstance / LivePrimitive, ChannelObject, PathChangeEvent / PathChangeListener, PathSubscriptionOptions, and a new public ObjectMessage` interface — all Java 8 compatible.
• Cross-SDK alignment table with ably-js, the Kotlin draft and Python draft (from LiveObjects-path-base-api.pdf).
• Usage examples (root, atomic deep create, reads, writes, subscriptions, instance-pinned subs, snapshots, type-change resilience).
• Implementation plan mapped to actual paths in this repo (lib/Java surface, liveobjects/ Kotlin internals), phased delivery, and migration table.
• §15 codebase audit — 16 inconsistencies between the v1 sketch and the real source tree, each with a source-line citation and the fix applied.

Key design decisions (highlights)

#	Decision
D1	PathObject is a single, untyped handle
D2	Strong typing lives on *Instance types
D3	Root is RootPathObject (the only fixed-type path)
D4	channel.object().get() (Java) / channel.realtimeObject.getRoot() (Kotlin)
D5	Introduce LivePrimitive
D6	LiveMapInstance / LiveCounterInstance extend internal types
D7	No LiveListPathObject
D8	compact() → Map<String, LiveValue>; compactJson() → JsonElement
D9	No MessageOptions
D10	Defined throw/null semantics
D11	Reads are non-blocking, writes are @Blocking (matches LiveMap / LiveCounter source)

Out of scope

• batch(...) operations
• REST API surface (AblyRest objects ops)
• LiveList

These are called out explicitly in §4 (Non-Goals) and tracked as future
work; none affect the decisions above.

[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: 9bee21c6-5b0a-4b80-ad19-afabfc70da36

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/path-based-liveobjects-public-api

---

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 and usage tips.}