[AIT-30] LiveObjects Path-based API spec

[VeskeR]

Note: This PR is based on #470; please review that one first.

Resolves AIT-30.

[lawrence-forooghian]

I've rebased this on main (main issues were some conflicts left over from the Markdown migration, and the "The client library must retain…" clauses of RTO11f18 and RTO12f16, which have been moved to RTLCV4g5 and RTLMV4j5).

I've also split it up a bit:

1. Implicit attach on channel.objects.getRoot() call #472 — now into main since the behaviour is not related to the path-based API
2. [AIT-30] Rename LiveObjects entrypoint and class name from "objects" to "object" #470 — simple rename targeting integration/liveobjects-path-based-api will approve and merge imminently
3. this PR, which now contains the core path-based API stuff — I intend to review shortly
4. [AIT-30] BatchContext and batch API on PathObject and Instance #471 — batch stuff, we can review this later since I don't think we need to ship a batch API as part of the initial path-based API release for Swift / Kotlin (given we don't yet have a batch API in those libraries and never treated it as a priority)

[Copilot]

Pull request overview

Updates the LiveObjects specification to introduce a path-based API surface (PathObject) and value-type factories (LiveMapValueType, LiveCounterValueType) to support nested object creation and path-scoped subscriptions, superseding the previous RealtimeObject#createMap/createCounter style.

Changes:

• Replace RealtimeObject#get() return type with PathObject, and specify path resolution, navigation, and path-based subscriptions.
• Introduce immutable “value types” (LiveMapValueType, LiveCounterValueType) created via LiveMap.create / LiveCounter.create, consumed by mutation operations to emit the required *_CREATE messages.
• Add a shared Subscription type to features.md and update reserved spec point prefixes / message-size retention references to the new clauses.

Reviewed changes

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

File	Description
specifications/objects-features.md	Specifies the new path-based API (PathObject, Instance), value-type creation/consumption, and subscription dispatch rules; updates the IDL accordingly.
specifications/features.md	Extends reserved spec point prefixes, updates retention references, and defines a shared Subscription type in the core feature spec/IDL.

Comments suppressed due to low confidence (3)

specifications/objects-features.md:298

• RTO24b4 requires dispatching a PathObjectSubscriptionEvent that includes the ObjectMessage that caused the change, but the trigger described in RTO24b is a LiveObjectUpdate emission (RTLO4b4), which doesn’t carry an ObjectMessage. Please clarify how the ObjectMessage is made available at dispatch time (e.g. include it in the emitted update, or define PathObjectSubscriptionRegister as being driven directly by operation application).

  - `(RTO24b)` When a `LiveObject` in the `ObjectsPool` emits a `LiveObjectUpdate` (per [RTLO4b4](#RTLO4b4)), the `PathObjectSubscriptionRegister` must determine which subscriptions should be notified:
    - `(RTO24b1)` Determine the paths in the LiveObjects tree at which the updated `LiveObject` is located
    - `(RTO24b2)` For each registered subscription, check whether the event path starts with (or equals) the subscription's path
    - `(RTO24b3)` If the event path matches, apply depth filtering: the event is dispatched to the subscription if the number of path segments from the subscription path to the event path plus 1 does not exceed the subscription's `depth` option (or if `depth` is undefined). Formally, the event is dispatched if `eventPath.length - subscriptionPath.length + 1 <= depth`
    - `(RTO24b4)` Create a `PathObjectSubscriptionEvent` with a `PathObject` pointing to the event path and the `ObjectMessage` that caused the change, and call the subscription's listener
    - `(RTO24b5)` If a listener throws an error, the error must be caught and logged without affecting the dispatch to other subscriptions

specifications/objects-features.md:1032

• RTLO4b4b explicitly states that LiveObjectUpdate.noop is an internal property, but the IDL no longer marks it as internal. Either mark noop as internal in the IDL (or make the surrounding text consistent if it’s intended to be public).

    interface LiveObjectUpdate: // RTLO4b4
      update: Object // RTLO4b4a
      noop: Boolean // RTLO4b4b

specifications/objects-features.md:1052

• The IDL marks LiveMap as internal, but the spec introduces LiveMap.create (RTLMV3) as the public factory for LiveMapValueType. If LiveMap is internal, users can’t call LiveMap.create, so either LiveMap needs to be public (with only instance methods internal), or the factory should live on a public type (e.g. LiveMapValueType.create).

    class LiveMap extends LiveObject: // RTLM*, RTLM1, internal
      clearTimeserial: String? // RTLM25, internal
      get(key: String) -> (Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounter | LiveMap)? // RTLM5, internal
      size() -> Number // RTLM10, internal
      entries() -> [String, (Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounter | LiveMap)?][] // RTLM11, internal
      keys() -> String[] // RTLM12, internal
      values() -> (Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounter | LiveMap)?[] // RTLM13, internal
      set(String key, (Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounterValueType | LiveMapValueType) value) => io // RTLM20, internal
      remove(String key) => io // RTLM21, internal
      static create(Dict<String, Boolean | Binary | Number | String | JsonArray | JsonObject | LiveCounterValueType | LiveMapValueType> entries?) -> LiveMapValueType // RTLMV3

---

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