Improve phrasing and clarify a couple of spec points

Author: VeskeR

src/objects-features.md

@@ -27,7 +27,8 @@ the latest state.
   - `(RTO1a)` Requires the `OBJECT_SUBSCRIBE` channel mode to be granted
     per [RTO2](#RTO2)
   - `(RTO1b)` If the channel is in the `DETACHED` or `FAILED` state, the
-    library should indicate an error with code 90001
+    library should throw an `ErrorInfo` error with `statusCode` 400 and
+    `code` 90001
   - `(RTO1c)` Waits for the objects sync sequence to complete and for
     [RTO5c](#RTO5c) to finish
   - `(RTO1d)` Returns the object with id `root` from the internal
@@ -41,23 +42,28 @@ the latest state.
     - `(RTO2a1)` If the channel mode is in the set, the operation is
       allowed
     - `(RTO2a2)` If the channel mode is missing, unless otherwise
-      specified by the operation, the library should indicate an error
-      with code 40024 stating that the operation cannot be performed
-      without the required channel mode
+      specified by the operation, the library should throw an
+      `ErrorInfo` error with `statusCode` 400 and `code` 40024,
+      indicating that the operation cannot be performed without the
+      required channel mode
   - `(RTO2b)` Otherwise, a best-effort attempt is made, and the channel
     mode is checked against the set of channel modes requested by the
     user per [TB2d](../features#TB2d) :
     - `(RTO2b1)` If the channel mode is in the set, the operation is
       allowed
     - `(RTO2b2)` If the channel mode is missing, unless otherwise
-      specified by the operation, the library should indicate an error
-      with code 40024 stating that the operation cannot be performed
-      without the required channel mode
+      specified by the operation, the library should throw an
+      `ErrorInfo` error with `statusCode` 400 and `code` 40024,
+      indicating that the operation cannot be performed without the
+      required channel mode
 - `(RTO3)` An internal `ObjectsPool` should be used to maintain the list
   of objects present on a channel
   - `(RTO3a)` `ObjectsPool` is a `Dict<String, LiveObject>` - a map of
     `LiveObject`s keyed by [`objectId`](../features#OST2a) string
   - `(RTO3b)` It must always contain a `LiveMap` object with id `root`
+    - `(RTO3b1)` Upon initialization of the `ObjectsPool`, create a new
+      `LiveMap` (per [RTLM4](#RTLM4)) with `objectId` set to `root` and
+      add it to the `ObjectsPool`
 - `(RTO4)` When a channel `ATTACHED` `ProtocolMessage` is received, the
   `ProtocolMessage` may contain a `HAS_OBJECTS` bit flag indicating that
   it will perform an objects sync, see [TR3](../features#TR3) . Note
@@ -72,7 +78,10 @@ the latest state.
     - `(RTO4b1)` All objects except the one with id `root` must be
       removed from the internal `ObjectsPool`
     - `(RTO4b2)` The data for the `LiveMap` with id `root` must be
-      cleared by setting it to a zero-value per [RTLM4](#RTLM4)
+      cleared by setting it to a zero-value per [RTLM4](#RTLM4). Note
+      that the client SDK must not create a new `LiveMap` instance with
+      id `root`; it must only clear the internal data of the existing
+      `LiveMap` with id `root`
     - `(RTO4b3)` The `SyncObjectsPool` must be cleared
     - `(RTO4b4)` Perform the actions for objects sync completion as
       described in [RTO5c](#RTO5c)
@@ -102,27 +111,27 @@ the latest state.
     temporarily stored in the internal `SyncObjectsPool` list
   - `(RTO5c)` When the objects sync has completed, the client library
     must perform the following actions in order:
-    - `(RTO5c1)` For each `ObjectState` member in the `SyncObjectsPool`
-      list:
+    - `(RTO5c1)` For each `ObjectState` in the `SyncObjectsPool` list:
       - `(RTO5c1a)` If an object with `ObjectState.objectId` exists in
         the internal `ObjectsPool`:
-        - `(RTO5c1a1)` Override the internal data for the object as per
-          [RTLC6](#RTLC6), [RTLM6](#RTLM6)
+        - `(RTO5c1a1)` Replace the internal data for the object as
+          described in [RTLC6](#RTLC6) or [RTLM6](#RTLM6) depending on
+          the object type, passing in current `ObjectState`
       - `(RTO5c1b)` If an object with `ObjectState.objectId` does not
         exist in the internal `ObjectsPool`:
         - `(RTO5c1b1)` Create a new `LiveObject` using the data from
           `ObjectState` and add it to the internal `ObjectsPool`:
           - `(RTO5c1b1a)` If `ObjectState.counter` is present, create a
             zero-value `LiveCounter` (per [RTLC4](#RTLC4)), set its
             private `objectId` equal to `ObjectState.objectId` and
-            override its internal data using the current `ObjectState`
+            replace its internal data using the current `ObjectState`
             per [RTLC6](#RTLC6)
           - `(RTO5c1b1b)` If `ObjectState.map` is present, create a
             zero-value `LiveMap` (per [RTLM4](#RTLM4)), set its private
             `objectId` equal to `ObjectState.objectId`, set its private
-            `semantics` equal to `ObjectState.map.semantics` and
-            override its internal data using the current `ObjectState`
-            per [RTLM6](#RTLM6)
+            `semantics` equal to `ObjectState.map.semantics` and replace
+            its internal data using the current `ObjectState` per
+            [RTLM6](#RTLM6)
           - `(RTO5c1b1c)` Otherwise, log a warning that an unsupported
             object state message has been received, and discard the
             current `ObjectState` without taking any action
@@ -148,6 +157,11 @@ the latest state.
     - `(RTO6b3)` If the parsed type is `counter`, create a zero-value
       `LiveCounter` per [RTLC4](#RTLC4) in the `ObjectsPool`
 
+### LiveObject
+
+- `(RTLO1)` The `LiveObject` represents the common interface and
+  includes shared functionality for concrete object types
+
 ### LiveCounter
 
 - `(RTLC1)` The `LiveCounter` extends `LiveObject`
@@ -160,9 +174,10 @@ the latest state.
   - `(RTLC5a)` Requires the `OBJECT_SUBSCRIBE` channel mode to be
     granted per [RTO2](#RTO2)
   - `(RTLC5b)` If the channel is in the `DETACHED` or `FAILED` state,
-    the library should indicate an error with code 90001
+    the library should throw an `ErrorInfo` error with `statusCode` 400
+    and `code` 90001
   - `(RTLC5c)` Returns the current `data` value
-- `(RTLC6)` `LiveCounter`’s internal `data` can be overridden with the
+- `(RTLC6)` `LiveCounter`’s internal `data` can be replaced with the
   provided `ObjectState` in the following way:
   - `(RTLC6a)` Replace the private `siteTimeserials` of the
     `LiveCounter` with the value from `ObjectState.siteTimeserials`
@@ -188,7 +203,8 @@ the latest state.
   - `(RTLM5b)` Requires the `OBJECT_SUBSCRIBE` channel mode to be
     granted per [RTO2](#RTO2)
   - `(RTLM5c)` If the channel is in the `DETACHED` or `FAILED` state,
-    the library should indicate an error with code 90001
+    the library should throw an `ErrorInfo` error with `statusCode` 400
+    and `code` 90001
   - `(RTLM5d)` Returns the value from the current `data` at the
     specified key, as follows:
     - `(RTLM5d1)` If no `ObjectsMapEntry` exists at the key, return
@@ -208,8 +224,8 @@ the latest state.
         - `(RTLM5d2f2)` If an object with id `objectId` exists, return
           it
       - `(RTLM5d2g)` Otherwise, return undefined/null
-- `(RTLM6)` `LiveMap` internal `data` can be overridden with the
-  provided `ObjectState` in the following way:
+- `(RTLM6)` `LiveMap` internal `data` can be replaced with the provided
+  `ObjectState` in the following way:
   - `(RTLM6a)` Replace the private `siteTimeserials` of the `LiveMap`
     with the value from `ObjectState.siteTimeserials`
   - `(RTLM6b)` Set the private flag `createOperationIsMerged` to `false`
@@ -218,22 +234,23 @@ the latest state.
   - `(RTLM6d)` If `ObjectState.createOp` is present:
     - `(RTLM6d1)` For each key–@ObjectsMapEntry@ pair in
       `ObjectState.createOp.map.entries`:
-      - `(RTLM6d1a)` If `ObjectsMapEntry.tombstone` is `false`, apply
-        the `MAP_SET` operation to the specified key using
-        `ObjectsMapEntry.timeserial` and `ObjectsMapEntry.data` per
-        [RTLM7](#RTLM7)
+      - `(RTLM6d1a)` If `ObjectsMapEntry.tombstone` is `false` or
+        omitted, apply the `MAP_SET` operation to the specified key
+        using `ObjectsMapEntry.timeserial` and `ObjectsMapEntry.data`
+        per [RTLM7](#RTLM7)
       - `(RTLM6d1b)` If `ObjectsMapEntry.tombstone` is `true`, apply the
         `MAP_REMOVE` operation to the specified key using
         `ObjectsMapEntry.timeserial` per [RTLM8](#RTLM8)
     - `(RTLM6d2)` Set the private flag `createOperationIsMerged` to
       `true`
 - `(RTLM7)` `MAP_SET` operation for a key can be applied to a `LiveMap`
   in the following way:
-  - `(RTLM7a)` If an entry exists in the private `data` for the
-    specified key:
-    - `(RTLM7a1)` If the operation cannot be applied as per
-      [RTLM9](#RTLM9), discard the operation without taking any action
-    - `(RTLM7a2)` Otherwise, apply the operation:
+  - `(RTLM7a)` If an `ObjectsMapEntry` exists in the private `data` for
+    the specified key:
+    - `(RTLM7a1)` If the operation cannot be applied to the existing
+      entry as per [RTLM9](#RTLM9), discard the operation without taking
+      any action
+    - `(RTLM7a2)` Otherwise, apply the operation to the existing entry:
       - `(RTLM7a2a)` Set `ObjectsMapEntry.data` to the `ObjectData` from
         the operation
       - `(RTLM7a2b)` Set `ObjectsMapEntry.timeserial` to the operation’s
@@ -247,15 +264,17 @@ the latest state.
       `false`
   - `(RTLM7c)` If the operation has a non-empty `ObjectData.objectId`
     attribute:
-    - `(RTLM7c1)` Create a zero-value `LiveObject` in the internal
-      `ObjectsPool` per [RTO6](#RTO6)
+    - `(RTLM7c1)` Create a zero-value `LiveObject` for this
+      `ObjectData.objectId` in the internal `ObjectsPool` per
+      [RTO6](#RTO6)
 - `(RTLM8)` `MAP_REMOVE` operation for a key can be applied to a
   `LiveMap` in the following way:
-  - `(RTLM8a)` If an entry exists in the private `data` for the
-    specified key:
-    - `(RTLM8a1)` If the operation cannot be applied as per
-      [RTLM9](#RTLM9), discard the operation without taking any action
-    - `(RTLM8a2)` Otherwise, apply the operation:
+  - `(RTLM8a)` If an `ObjectsMapEntry` exists in the private `data` for
+    the specified key:
+    - `(RTLM8a1)` If the operation cannot be applied to the existing
+      entry as per [RTLM9](#RTLM9), discard the operation without taking
+      any action
+    - `(RTLM8a2)` Otherwise, apply the operation to the existing entry:
       - `(RTLM8a2a)` Set `ObjectsMapEntry.data` to undefined/null
       - `(RTLM8a2b)` Set `ObjectsMapEntry.timeserial` to the operation’s
         serial
@@ -269,19 +288,19 @@ the latest state.
       `true`
 - `(RTLM9)` Whether a map operation can be applied to a map entry is
   determined as follows:
-  - `(RTLM9a)` For a `LiveMap` using `LWW` (Last-Write-Wins) CRDT
-    semantics, the operation must only be applied if its serial is
-    strictly greater (”after”) than the entry’s serial when compared
-    lexicographically
+  - `(RTLM9a)` For a `LiveMap` with `semantics` set to
+    `ObjectsMapSemantics.LWW` (Last-Write-Wins CRDT semantics), the
+    operation must only be applied if its serial is strictly greater
+    (”after”) than the entry’s serial when compared lexicographically
   - `(RTLM9b)` If both the entry serial and the operation serial are
     null or empty strings, they are treated as the “earliest possible”
     serials and considered “equal”, so the operation must not be applied
-  - `(RTLM9c)` If only the entry serial exists, the missing operation
-    serial is considered lower than the existing entry serial, so the
-    operation must not be applied
-  - `(RTLM9d)` If only the operation serial exists, it is considered
-    greater than the missing entry serial, so the operation can be
-    applied
-  - `(RTLM9e)` If both serials exist, compare them lexicographically and
-    allow operation to be applied only if the operation’s serial is
-    greater than the entry’s serial
+  - `(RTLM9c)` If only the entry serial exists and is not an empty
+    string, the missing operation serial is considered lower than the
+    existing entry serial, so the operation must not be applied
+  - `(RTLM9d)` If only the operation serial exists and is not an empty
+    string, it is considered greater than the missing entry serial, so
+    the operation can be applied
+  - `(RTLM9e)` If both serials exist and are not empty strings, compare
+    them lexicographically and allow operation to be applied only if the
+    operation’s serial is greater than the entry’s serial