From a4f5929f90006bca81809e737effcc35e809bb01 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 28 Jan 2026 14:01:08 -0300
Subject: [PATCH] Update JS LiveObjects documentation for apply-on-ACK

This reflects the functionality implemented in [1], based on the DR
[2] and spec [3]. Written by Claude.

[1] https://github.com/ably/ably-js/pull/2155
[2] https://ably.atlassian.net/wiki/spaces/LOB/pages/4671832082/LODR-054+SDK+apply+operations+on+ACK)
[3] https://github.com/ably/specification/pull/419
---
 src/pages/docs/liveobjects/batch.mdx                  |  2 +-
 .../docs/liveobjects/concepts/synchronization.mdx     | 11 +++++++++++
 src/pages/docs/liveobjects/quickstart/javascript.mdx  |  2 +-
 src/pages/docs/platform/errors/codes.mdx              |  4 ++++
 4 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/pages/docs/liveobjects/batch.mdx b/src/pages/docs/liveobjects/batch.mdx
index 1ddbb21a09..04b5734a71 100644
--- a/src/pages/docs/liveobjects/batch.mdx
+++ b/src/pages/docs/liveobjects/batch.mdx
@@ -198,7 +198,7 @@ try {
 </Code>
 
 <Aside data-type='note'>
-Although the batch context provides a synchronous API, updates to objects are only applied _after_ the batch callback function has run and changes have been echoed back to the client, like regular mutation operations.
+Although the batch context provides a synchronous API, updates to objects are only applied _after_ the batch callback function has run and the changes have been acknowledged by the Ably system. When the `batch()` promise resolves, all operations have been applied and you can immediately read the updated state.
 </Aside>
 
 Since the batch callback is synchronous, you can read current values inside a batch context without intermediate updates from other clients being applied between reads:
diff --git a/src/pages/docs/liveobjects/concepts/synchronization.mdx b/src/pages/docs/liveobjects/concepts/synchronization.mdx
index 795ce1d899..c1c28a28b0 100644
--- a/src/pages/docs/liveobjects/concepts/synchronization.mdx
+++ b/src/pages/docs/liveobjects/concepts/synchronization.mdx
@@ -51,8 +51,19 @@ Calling [`channel.object.get()`](/docs/liveobjects/concepts/objects#channel-obje
 
 All object operations published to the channel are broadcast to subscribed clients, which apply the operations to their local client objects when they are received. This allows clients to maintain a consistent view of the channel objects in a bandwidth-efficient way, since only the operations (rather than the updated objects themselves) are sent over the client's connection.
 
+<If lang="javascript">
+<Aside data-type='note'>
+When a client publishes an operation, the operation is applied to its local objects as soon as the operation is acknowledged by the Ably system. This means that when a mutation method's promise resolves, the operation has already been applied and you can immediately read the updated state.
+</Aside>
+
+<Aside data-type='important'>
+If you're also developing with the Swift or Java SDKs, note that they currently apply operations when [echoed](/docs/pub-sub/advanced#echo) back from the server rather than on acknowledgment. Apply-on-acknowledgment is coming soon to those SDKs.
+</Aside>
+</If>
+<If lang="swift,java">
 <Aside data-type='note'>
 Currently, when a client publishes an operation it is not immediately applied to its local objects. Instead, the client only applies the operation when the operation is [echoed](/docs/pub-sub/advanced#echo) back to the client.
 </Aside>
+</If>
 
 If there is a loss of continuity on the channel for any reason, such as the client becoming disconnected for more than two minutes and entering the [suspended state](/docs/connect/states#connection-states), the client objects will automatically be resynchronized when it reconnects.
diff --git a/src/pages/docs/liveobjects/quickstart/javascript.mdx b/src/pages/docs/liveobjects/quickstart/javascript.mdx
index c634039382..3ee1d2ffc3 100644
--- a/src/pages/docs/liveobjects/quickstart/javascript.mdx
+++ b/src/pages/docs/liveobjects/quickstart/javascript.mdx
@@ -200,7 +200,7 @@ await reactionsMap.remove('likes');
 </Code>
 
 <Aside data-type='note'>
-Mutation methods do not directly modify the local object state. Instead, they send operations to the Ably system, and changes are applied when the operations are echoed back to the client. This means the state retrieved immediately after a mutation may not reflect the latest updates yet. You will be notified via subscription when the object is updated.
+Mutation methods send operations to the Ably system and apply changes locally as soon as the operations are acknowledged. When a mutation method's promise resolves, the operation has been applied and you can immediately read the updated state. You will also be notified via subscription when the object is updated.
 </Aside>
 
 ## Next steps <a id="step-8"/>
diff --git a/src/pages/docs/platform/errors/codes.mdx b/src/pages/docs/platform/errors/codes.mdx
index acac0bd4e4..26c6d51728 100644
--- a/src/pages/docs/platform/errors/codes.mdx
+++ b/src/pages/docs/platform/errors/codes.mdx
@@ -766,6 +766,10 @@ You may encounter this error when the type of the object located at the specifie
 Resolution:
 * Ensure that the operation is valid for the type of object at the specified path.
 
+## 92008: Unable to apply objects operation; objects sync did not complete <a id="92008"/>
+
+This error occurs when a LiveObjects mutation operation has been successfully published to the server, but the operation could not be applied locally because the channel entered the `DETACHED`, `SUSPENDED`, or `FAILED` state while waiting for the objects sync to complete. The operation will still take effect on the server, but the local state may not reflect it until the channel is re-attached and the objects are re-synced.
+
 ## 93001: Attempt to add an annotation listener without having requested the annotation_subscribe channel mode <a id="93001"/>
 
 This error occurs when attempting to [subscribe to individual annotations](/docs/messages/annotations#subscribe-individual-annotations) without having requested the `annotation_subscribe` [channel mode](/docs/channels/options#modes) .