[PUB-1829] Add object-level write API spec for RealtimeObjects

[VeskeR]

Adds spec for:

• RealtimeObjects.createMap
• RealtimeObjects.createCounter

Related DRs: LLODR-027: OBJECT_ID semantic preserving client-side generated IDs (Object ID generation), LODR-018: High level write API overview

Resolves PUB-1829

[sacOO7]

Since the connection can be shared across PubSub, Chat, and Objects, echoMessages might limit the ability to do so. We need to assess the potential impact across various product offerings

[VeskeR]

I've opened a separate issue for this #365, and this can be discussed in future LiveObjects plugin discussions.
As of now, LiveObjects does not support applying operations locally first and instead relies on receiving echoed operations.

[sacOO7]

In the case of REST APIs, objectId is optional and is automatically generated by the server.
Applying the same approach for realtime could reduce round-trip time for getting current server time —something particularly valuable when customers are using RealtimeObjects.
Although we're using the local offset to save round-trip time for subsequent requests, there's still a risk that the local clock may drift out of sync.
So, we can keep objectId generation optional in realtime as well, wdyt

[sacOO7]

Why Clock Drift Happens

• Hardware limitations: Even in modern servers, clock crystals have a natural drift—often ±20 parts per million (ppm) or better—leading to seconds or even minutes of drift over long periods if completely unsynchronized.
• Virtualization effects: Virtual machines (VMs) are affected by host clock changes, hypervisor scheduling, and pausing (such as during suspension or migration). This can lead to sudden jumps or drift in the OS-reported time.
• Synchronization interruptions: Network Time Protocol (NTP), Precision Time Protocol (PTP), and cloud-provider time sync services are used to keep clocks accurate. Any network issue, misconfiguration, or system trouble that prevents time sync can allow drift to accumulate, sometimes rapidly.
• System events: Actions such as rebooting, resuming from suspension, or falling back to OS instead of the hardware clock can cause higher drift or a temporary loss of sync

[VeskeR]

In Realtime, developers can obtain a reference to an object before the corresponding *_CREATE operation has been processed by the server and an ID has been generated for it. In such cases, it is crucial that the Realtime client is still able to send mutation operations for that object or reference it within other collection types. Without knowing the object ID, this becomes impossible and would require implementing a queuing mechanism, which would quickly become complex and difficult to manage.

The need for client-generated object IDs is further emphasized by the new path-based API and the proposed object creation changes here. Object creation is no longer an async method but instead a simple call like LiveCounter.create(), which returns a value type describing the structure of the object.

Furthermore, the end goal of the LiveObjects plugin is to provide a local-first, offline-first API, where changes can be made entirely offline on the client side and later synced via Realtime across all other clients. This is only possible if the client is able to generate object IDs.

For the REST API, all of the above is not relevant, so we can rely on the server to generate object IDs.

[sacOO7]

We can make RTO11f10, RTO11f11.. etc as subpoints of RTO11f9, since we are constructing ObjectMessage for MapCreateOperation right

[VeskeR]

I think the current structure is correct. The parent RTO11f specifies that an ObjectMessage for a MAP_CREATE action can be created by following its sub-items. You then simply follow these sub-items in sequence to construct the correct ObjectMessage.
It makes sense for RTO11f10 and the following items to be at the same level as RTO11f9 and the other RTO11f* entries, as they all describe the steps required to create the ObjectMessage.

[sacOO7]

lgtm