@fluidframework/tree 2.10.0-306579 → 2.10.0-307399

package/docs/.attachments/object-merge-semantics.drawio

@@ -0,0 +1,145 @@
+<mxfile host="Electron" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.7.17 Chrome/128.0.6613.36 Electron/32.0.1 Safari/537.36" version="24.7.17">
+  <diagram id="-6H5wynXqOOyBtFPYk5a" name="Page-1">
+    <mxGraphModel dx="1058" dy="-74" grid="1" gridSize="10" guides="1" tooltips="1" connect="0" arrows="0" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" background="#ffffff" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="ug50JPKoQ96zgBhktdCE-255" value="" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+          <mxGeometry x="894.68" y="1500" width="640" height="120" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-256" value="" style="group" parent="1" vertex="1" connectable="0">
+          <mxGeometry x="936.0312457912456" y="1510" width="558.6531986531986" height="88.0383333333333" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-257" value="" style="group" parent="ug50JPKoQ96zgBhktdCE-256" vertex="1" connectable="0">
+          <mxGeometry y="39.99666666666667" width="558.6531986531986" height="48.04166666666663" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-258" value="Period of time where a client&#39;s local state shows the sticky note with a &lt;font color=&quot;#ffd966&quot;&gt;&lt;b&gt;yellow&lt;/b&gt;&lt;/font&gt; backgound" style="text;html=1;align=left;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeWidth=2;labelPosition=center;verticalLabelPosition=middle;" parent="ug50JPKoQ96zgBhktdCE-257" vertex="1">
+          <mxGeometry x="58.65319865319864" width="500" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-259" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FFD966;strokeColor=none;points=[];" parent="ug50JPKoQ96zgBhktdCE-257" vertex="1">
+          <mxGeometry y="12.708333333333336" width="38.35016835016835" height="4.583333333333333" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-260" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FF6666;strokeColor=#b85450;points=[];strokeWidth=0;" parent="ug50JPKoQ96zgBhktdCE-257" vertex="1">
+          <mxGeometry x="1.77635683940025e-15" y="30.749999999999957" width="38.35016835016835" height="4.583333333333333" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-261" value="Period of time where a client&#39;s local state shows the sticky note with a &lt;b style=&quot;&quot;&gt;&lt;font color=&quot;#ff6666&quot;&gt;red&lt;/font&gt;&lt;/b&gt;&amp;nbsp;backgound" style="text;html=1;align=left;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeWidth=2;labelPosition=center;verticalLabelPosition=middle;" parent="ug50JPKoQ96zgBhktdCE-257" vertex="1">
+          <mxGeometry x="58.65319865319864" y="18.04166666666663" width="480" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-262" value="edit" style="shape=callout;whiteSpace=wrap;html=1;perimeter=calloutPerimeter;size=20;position=0.5;base=10;strokeWidth=2;" parent="ug50JPKoQ96zgBhktdCE-256" vertex="1">
+          <mxGeometry x="39.998754208754235" width="45.12" height="35.83" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-263" value="An edit being initiated" style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeWidth=2;" parent="ug50JPKoQ96zgBhktdCE-256" vertex="1">
+          <mxGeometry x="85.11424242424255" y="0.3125" width="140" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-264" value="An edit being transmitted" style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeWidth=2;" parent="ug50JPKoQ96zgBhktdCE-256" vertex="1">
+          <mxGeometry x="349.39525252525254" y="0.3158333333333303" width="150" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-265" value="" style="endArrow=classic;html=1;strokeWidth=2;" parent="ug50JPKoQ96zgBhktdCE-256" edge="1">
+          <mxGeometry x="1294.4444444444443" y="400" width="45.11784511784512" height="45.833333333333336" as="geometry">
+            <mxPoint x="302.94875420875405" y="9" as="sourcePoint" />
+            <mxPoint x="349.03989898989903" y="9.482500000000073" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-266" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#3399FF;strokeColor=#b85450;points=[];strokeWidth=0;" parent="1" vertex="1">
+          <mxGeometry x="936.0312457912456" y="1598.7066666666667" width="38.35016835016835" height="4.583333333333333" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-267" value="Period of time where a client&#39;s local state shows the sticky note with a &lt;b style=&quot;&quot;&gt;&lt;font color=&quot;#3399ff&quot;&gt;blue&lt;/font&gt;&lt;/b&gt;&amp;nbsp;backgound" style="text;html=1;align=left;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeWidth=2;labelPosition=center;verticalLabelPosition=middle;" parent="1" vertex="1">
+          <mxGeometry x="994.6844444444442" y="1585.9983333333334" width="490" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-140" value="" style="endArrow=none;html=1;exitX=0.875;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;strokeWidth=2;" parent="1" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="936.5" y="1440.5" as="sourcePoint" />
+            <mxPoint x="1559" y="1441" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-142" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#3399FF;strokeColor=#b85450;points=[];strokeWidth=0;" parent="1" vertex="1">
+          <mxGeometry x="1079" y="1441" width="481" height="5" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-143" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FFD966;strokeColor=none;points=[];" parent="1" vertex="1">
+          <mxGeometry x="936.5" y="1441" width="142.5" height="5" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-144" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#3399ff;strokeColor=#b85450;points=[];strokeWidth=0;" parent="1" vertex="1">
+          <mxGeometry x="1319" y="1281" width="240" height="5" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-145" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FF6666;strokeColor=#b85450;points=[];strokeWidth=0;" parent="1" vertex="1">
+          <mxGeometry x="1000" y="1281" width="319" height="5" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-146" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#FFD966;strokeColor=none;points=[];" parent="1" vertex="1">
+          <mxGeometry x="941.5" y="1281" width="58.5" height="5" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-179" value="&lt;div&gt;Alice&lt;/div&gt;" style="shape=umlActor;verticalLabelPosition=bottom;verticalAlign=top;html=1;outlineConnect=0;strokeWidth=2;" parent="1" vertex="1">
+          <mxGeometry x="891.5" y="1251" width="25" height="50" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-180" value="&lt;div&gt;Bob&lt;/div&gt;" style="shape=umlActor;verticalLabelPosition=bottom;verticalAlign=top;html=1;outlineConnect=0;strokeWidth=2;" parent="1" vertex="1">
+          <mxGeometry x="891.5" y="1411" width="25" height="50" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-181" value="Service" style="ellipse;shape=cloud;whiteSpace=wrap;html=1;strokeWidth=2;" parent="1" vertex="1">
+          <mxGeometry x="869" y="1331" width="70" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-182" value="" style="endArrow=none;html=1;exitX=0.875;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;strokeWidth=2;" parent="1" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="941.5" y="1280" as="sourcePoint" />
+            <mxPoint x="1559" y="1281" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-183" value="" style="endArrow=none;html=1;exitX=0.875;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;strokeWidth=2;" parent="1" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="936.5" y="1360.5" as="sourcePoint" />
+            <mxPoint x="1559" y="1361" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-184" value="Set color to red" style="shape=callout;whiteSpace=wrap;html=1;perimeter=calloutPerimeter;size=20;position=0.5;base=10;strokeWidth=2;fillColor=#f8cecc;strokeColor=#b85450;" parent="1" vertex="1">
+          <mxGeometry x="956" y="1241" width="90" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-185" value="" style="endArrow=classic;html=1;exitX=0;exitY=0;exitDx=40;exitDy=40;exitPerimeter=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=2;" parent="1" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="999" y="1281" as="sourcePoint" />
+            <mxPoint x="1119" y="1360" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-187" value="" style="endArrow=classic;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=2;exitX=0.5;exitY=1.025;exitDx=0;exitDy=0;exitPerimeter=0;" parent="1" source="ug50JPKoQ96zgBhktdCE-189" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1079" y="1481" as="sourcePoint" />
+            <mxPoint x="1199" y="1361" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-188" value="" style="endArrow=classic;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=2;" parent="1" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1199" y="1360" as="sourcePoint" />
+            <mxPoint x="1319" y="1281" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-189" value="" style="shape=callout;whiteSpace=wrap;html=1;perimeter=calloutPerimeter;size=20;position=0.5;base=10;strokeWidth=2;rotation=-180;flipH=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1">
+          <mxGeometry x="1030" y="1441" width="100" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-190" value="Set color to blue" style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeWidth=2;" parent="1" vertex="1">
+          <mxGeometry x="1025" y="1456" width="110" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-206" value="A" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fontStyle=1;fillColor=#f5f5f5;fontColor=#333333;strokeColor=#666666;" parent="1" vertex="1">
+          <mxGeometry x="1230" y="1411" width="20" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="ug50JPKoQ96zgBhktdCE-186" value="" style="endArrow=classic;html=1;exitX=0;exitY=0;exitDx=40;exitDy=40;exitPerimeter=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=2;" parent="1" edge="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1119" y="1361" as="sourcePoint" />
+            <mxPoint x="1240" y="1440" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="S-uX2zywk3RNg50cfgGr-1" value="" style="endArrow=classic;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=2;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1200" y="1361" as="sourcePoint" />
+            <mxPoint x="1320" y="1440" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="S-uX2zywk3RNg50cfgGr-2" value="" style="endArrow=classic;html=1;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=2;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1119" y="1360" as="sourcePoint" />
+            <mxPoint x="1239" y="1281" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="S-uX2zywk3RNg50cfgGr-5" value="B" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fontStyle=1;fillColor=#f5f5f5;fontColor=#333333;strokeColor=#666666;" vertex="1" parent="1">
+          <mxGeometry x="1309.5" y="1290" width="20" height="20" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

package/docs/user-facing/array-merge-semantics.md

@@ -0,0 +1,344 @@
+# Merge Semantics of Edits on Array Nodes
+
+This document describes the semantics of edits that can be performed on array nodes.
+
+Target audience: `SharedTree` users and maintainers.
+
+> While this document is self-contained, we recommend reading about [SharedTree's approach to merge semantics](merge-semantics) first.
+
+Each edit's merge semantics are defined in terms of the edit's preconditions and postconditions.
+A precondition defines a requirement that must be met for the edit to be valid.
+A postcondition defines a guarantee that is made about the effect of the edit.
+(Invalid edits are ignored along with all other edits in the same transaction, and postconditions do not hold).
+
+## Key Challenges and Solutions
+
+Before delving into the set editing operations supported by ShardTree arrays,
+it's helpful to understand the key challenges that come up when users are allowed to concurrently edit the same array,
+and how ShardTree arrays address these challenges.
+
+### Specifying the Location of Inserted Items
+
+#### The Problem
+
+Array operations that insert (or move in) array items take an integer that describes where in the array the new item(s) should be added.
+For example, we can call `insertAt(1, "o")` to insert the value `"o"` in the array `["c", "a", "t"]` thus changing it to  `["c", "o", "a", "t"]`.
+
+In a collaborative editing environment,
+it's possible for the state of the array to change between the time the edit is first created and the time it is applied.
+Consider what would happen if the argument that describes the destination of the insert were to be treated as a fixed integer index:
+
+Example 1:
+* Starting state: `["c", "a", "t"]`
+* Alice's edit: `insertAt(0, "r", "e", "d", " ")` with the expectation of getting `["r", "e", "d", " ", "c", "a", "t"]`.
+* Bob's edit: `insertAt(1, "o")` with the expectation of getting `["c", "o", "a", "t"]`.
+
+If Alice and Bob's edits are concurrent, and Alice's edit is sequenced first,
+then inserting `"o"` at index 1 would yield `["r", "o", "e", "d", " ", "c", "a", "t"]`.
+This would not truly match the intention of Bob,
+who would likely have wanted to get `["r", "e", "d", " ", "c", "o", "a", "t"]` instead.
+
+Example 2:
+* Starting state: `["r", "e", "d", " ", "c", "a", "t"]`
+* Alice's edit: `removeRange(0, 4)` with the expectation of getting `["c", "a", "t"]`.
+* Bob's edit: `insertAt(5, "o")` with the expectation of getting `["r", "e", "d", " ", "c", "o", "a", "t"]`.
+
+If Alice and Bob's edits are concurrent, and Alice's edit is sequenced first,
+then inserting `"o"` at index 5 would either crash or yield `["c", "a", "t", "o"]`.
+This would not truly match the intention of Bob,
+who would likely have wanted to get `["c", "o", "a", "t"]` instead.
+
+#### The Solution: Inserting in Gaps
+
+Instead of treating the destination parameter of insert and move operations as a fixed insertion index,
+SharedTree's array implementation interprets that parameter as referring to a gap in the array.
+
+For example, in an array with two items `[A, B]` there are three gaps:
+one before A, one between A and B, and one after C.
+If we represented gaps with the `_` character, then would describe the array `[A, B]` as `[ _ A _ B _ ]`.
+(More generally, an array with `K` items has `K+1` gaps.)
+
+This means that calling `insertAt(1, "o")` on an array with initial state `["c", "a", "t"]`
+singles out the following gap as the location to perform the insert: `["c" _ "a" "t"]`.
+This conversion from index 1 to the corresponding gap is done at the time the edit is first created.
+SharedTree's array implementation then keeps track of that gap's position when reconciling this insertion against concurrent edits.
+Reusing the scenario from example 1 in the previous section,
+the gap's position after reconciling with the concurrent edit from Alice (`insertAt(0, "r", "e", "d", " ")`)
+is as follows: `["r" "e" "d" " " "c" _ "a" "t"]`,
+thus yielding the adequate result after inserting "o" `["r", "e", "d", " ", "c", "o", "a", "t"]`.
+
+#### Tie-Breaking
+
+Note that multiple edits may concurrently attempt to insert or move in items into the same gap.
+When that's the case,
+the items end up ordered such that the items inserted by the edit that is sequenced earlier will appear after the items inserted by the edits that is sequenced later.
+
+Example:
+* Starting state: `[]`
+* Edit 1: (concurrently to edits 2 and 3) insert items A and B (this changes the state from `[]` to `[A, B]`)
+* Edit 2: (concurrently to edits 1 and 3) insert items R and S (this changes the state from `[]` to `[R, S]`)
+* Edit 3: (concurrently to edits 1 and 2) insert items X and Y (this changes the state from `[]` to `[X, Y]`)
+
+If the edits are sequenced in increasing order (i.e., edit 1, edit 2, edit 3),
+then the resulting state will be `[X, Y, R, S, A, B]`.
+
+#### Noteworthy Implications
+
+Creating an edit that inserts items before or after an existing item in an array will not necessarily insert next to that item.
+For example, inserting item X at the start of array `[Y, Z]` does not guarantee that X and Y will both appear together (in that order)
+if other users make concurrent edits to the array.
+
+Example 1: concurrent insert
+* Starting state: `[Y, Z]`
+* Alice's edit: insert A at the start of the array.
+* Bob's edit: insert X at the start of the array.
+If Alice's edit is sequenced before Bob's,
+then the result will be `[X, A, Y, Z]`.
+
+Example 2: concurrent remove
+* Starting state: `[Y, Z]`
+* Alice's edit: remove Y.
+* Bob's edit: insert X at the start of the array.
+No matter the order in which these edits are sequenced,
+the result will be `[X, Z]`.
+
+Example 3: concurrent move
+* Starting state: `[Y, Z]`
+* Alice's edit: move Y after Z.
+* Bob's edit: insert X at the start of the array.
+No matter the order in which these edits are sequenced,
+the result will be `[X, Z, Y]`
+as opposed to `[Z, X, Y]` which one might have expected if they thought of the insertion as happening "before Y".
+
+The takeaway from these examples is that while it's tempting to think of an insertion as occurring before or after an existing item,
+that doesn't quite match the merge semantics we have implemented.
+If you find yourself wishing for different merge semantics please reach out to the Fluid team.
+
+### Specifying the Set of (Re)Moved Items
+
+Each move or remove operations affects a specific set of array items.
+When a single item is targeted,
+the item can be specified using its index in the current state.
+For example, removing the `"o"` from `["c", "o", "a", "t"]` with `removeAt(1)`.
+
+When targeting multiple contiguous items,
+it is possible specify them as a range.
+For example, `"o"` and `"a"` from `["c", "o", "a", "t"]` with `removeRange(1, 3)`.
+
+From the point of view of merge semantics,
+calling `removeRange(1, 3)` is equivalent to individually removing each of the two middle letters in one transaction.
+Using the range-based API is typically more convenient.
+It is also optimized to have less overhead than making separate calls for each individual item.
+
+The same is true for `moveRange` compared to `moveAt`,
+with the additional property that `moveRange` preserves the order that the items are in at the time the edit is created.
+
+Example:
+* Starting state `[A, B, C]`
+* Edit 1: `moveRange(0, 1, 2)` (move B in the gap before A, yielding `[B, A, C]`)
+* Edit 2: `moveRange(3, 0, 2)` (move A and B in the gap after C, yielding `[C, A, B]`)
+
+If edit 1 is sequenced first, then, when edit 2 is finally applied,
+the state will change from `[B, A, C]` to `[C, A, B]`.
+If edit 2 is sequenced first, then, when edit 1 is finally applied,
+the state will change from `[C, A, B]`to `[B, C, A]`.
+
+#### The Problem
+
+In a collaborative editing environment,
+it's possible for the state of the array to change between the time the edit is first created and the time it is applied.
+Consider what would happen if the arguments that describe the affected items were to be treated as fixed integer indexes:  
+* Starting state: `["c", "o", "a", "t"]`
+* Alice's edit: `insertAt(0, "r", "e", "d", " ")` with the expectation of getting `["r", "e", "d", " ", "c", "o", "a", "t"]`.
+* Bob's edit: `removeAt(1)` with the expectation of getting `["c", "a", "t"]`.
+
+If Alice and Bob's edits are concurrent, and Alice's edit is sequenced first,
+then removing the item at index 1 would yield `["r", "d", " ", "c", "o", "a", "t"]`.
+This would not truly match the intention of Bob,
+who would likely have wanted to get `["r", "e", "d", " ", "c", "a", "t"]` instead.
+
+#### The Solution: Targeting Items
+
+Instead of treating the parameters of move and remove as a fixed index to detach items at,
+SharedTree's array implementation interprets these parameter as referring to the items themselves.
+In other words, `removeAt(1)` doesn't mean "remove whichever item happens to be at index 1 when the edit is applied".
+Instead, it means "remove the specific item that is currently at index 1, no matter what index that item it at when the edit is applied".
+
+#### Noteworthy Implications
+
+Inserting items within a range that is concurrently being moved has no impact on the set of moved items.
+For example, if one user moves items A and B to the end of array `[A, B, C]` by using a `sourceStart` of 0 and a `sourceEnd` of 2,
+and some other user concurrently inserts some item X between A and B (thus changing the state to `[A, X, B, C]`),
+then the move will still affect items A and B (and only these), thus yielding `[X, C, A, B]`.
+This is true no matter how the concurrent edits are ordered.
+
+If multiple users concurrently attempt to move the same item, the conflict is resolved in a last-write-wins fashion.
+For example, if one user moves item B leftward to the start of array `[A, B, C]`,
+and some other user concurrently moves item B rightward to the end of the array,
+then the item will be affected by each successive move in sequencing order:
+* If the leftward move is sequenced before the rightward move
+  then A will first be moved to the start (thus yielding `[B, A, C]`)
+  then moved to the end (thus yielding `[A, C, B]`).
+* If the rightward move is sequenced before the leftward move
+  then A will first be moved to the end (thus yielding `[A, C, B]`)
+  then moved to the start (thus yielding `[B, A, C]`).
+
+A removed item may be restored as a result of a concurrent move operation
+and a moved item may be removed as a result of a concurrent remove operation.
+For example, if one user moves item A to the end of array `[A, B, C]`,
+and some other user concurrently removes item A,
+then the item will be affected by each successive operation in sequencing order:
+* If the move is sequenced before the remove
+  then A will first be moved to the end of the array (thus yielding `[C, B, A]`)
+  then removed (thus yielding `[C, B]`).
+* If the remove is sequenced before the move
+  then A will first be removed (thus yielding `[C, B]`)
+  then moved (thus yielding `[C, B, A]`).
+
+## Core Editing Operations
+
+### `insertAt(gapIndex: number, ...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void`
+
+Inserts new items at the location described by `gapIndex`.
+
+Preconditions:
+* There is no concurrent schema change edit that is sequenced before this one.
+* The inserted values must have status `TreeStatus.New` or be primitives.
+  (This precondition will be removed soon)
+
+Postconditions:
+* The values are inserted in the targeted [gap](#location-of-inserted-items).
+
+### `moveRangeToIndex(destinationGap: number, sourceStart: number, sourceEnd: number, source: TMoveFrom): void`
+
+Moves the specified items from the given source array to the desired location within the array.
+
+Preconditions:
+* There is no concurrent schema change edit that is sequenced before this one.
+
+Postconditions:
+* The [specified items](#specifying-the-set-of-removed-items) are moved to the targeted [gap](#location-of-inserted-items).
+
+If multiple clients concurrently move an item,
+then that item will be moved to the destination indicated by the move of the client whose edit is sequenced last.
+
+### `removeRange(start?: number, end?: number): void`
+
+Removes the items between the specified indices.
+
+Preconditions:
+* There is no concurrent schema change edit that is sequenced before this one.
+
+Postconditions:
+* The [specified items](#specifying-the-set-of-removed-items) are removed.
+
+Removed items are saved internally for a time in case they need to be restored as a result of an undo operation.
+Changes made to them by concurrent edits will apply despite their removed status.
+
+## Other Operations
+
+The following operations are just syntactic sugar:
+
+`insertAtStart(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void`
+equates to `array.insertAt(0, ...value)`.
+
+`insertAtEnd(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void`
+equates to `array.insertAt(array.length, ...value)`.
+
+`moveRangeToIndex(destinationGap: number, sourceStart: number, sourceEnd: number): void`
+equates to `array.moveRangeToIndex(destinationGap, sourceStart, sourceEnd, array)`.
+
+`moveRangeToStart(sourceStart: number, sourceEnd: number, source: TMoveFrom): void`
+equates to `array.moveRangeToIndex(0, sourceStart, sourceEnd, source)`.
+
+`moveRangeToStart(sourceStart: number, sourceEnd: number): void`
+equates to `array.moveRangeToIndex(0, sourceStart, sourceEnd, array)`.
+
+`moveToIndex(destinationGap: number, sourceIndex: number, source: TMoveFrom): void`
+equates to `array.moveRangeToIndex(destinationGap, sourceIndex, sourceIndex+1, source)`.
+
+`moveToIndex(destinationGap: number, sourceIndex: number): void`
+equates to `array.moveRangeToIndex(destinationGap, sourceIndex, sourceIndex+1, array)`.
+
+`moveToStart(sourceIndex: number, source: TMoveFrom): void`
+equates to `array.moveRangeToIndex(0, sourceIndex, sourceIndex + 1, source)`.
+
+`moveToStart(sourceIndex: number): void`
+equates to `array.moveRangeToIndex(0, sourceIndex, sourceIndex + 1, array)`.
+
+`moveRangeToEnd(sourceStart: number, sourceEnd: number, source: TMoveFrom): void`
+equates to `array.moveRangeToIndex(array.length, sourceStart, sourceEnd, source)`.
+
+`moveRangeToEnd(sourceStart: number, sourceEnd: number): void`
+equates to `array.moveRangeToIndex(array.length, sourceStart, sourceEnd, array)`.
+
+`moveToEnd(sourceIndex: number, source: TMoveFrom): void`
+equates to `array.moveRangeToIndex(array.length, sourceIndex, sourceIndex + 1, source)`.
+
+`moveToEnd(sourceIndex: number): void`
+equates to `array.moveRangeToIndex(array.length, sourceIndex, sourceIndex + 1, array)`.
+
+`removeAt(index: number): void`
+equates to `array.removeRange(index, index + 1)`
+
+## Additional Notes
+
+### Operations on Removed Arrays
+
+All of the above operations are effective even when the targeted array has been moved or removed.
+
+### Removing and Re-inserting Items
+
+When dealing with plain JavaScript arrays,
+it is possible to move items around by removing them and adding them back in.
+For example, the item C can be moved to the start of the array `[A, B, C]` performing the following operations:
+```typescript
+const C = array.pop(); // Remove C -> [A, B]
+array.unshift(C); // Insert C at the start -> [C, A, B]
+```
+
+As of October 2024, SharedTree arrays do not support this pattern because it would require (re)inserting item C, which has previously been inserted.
+Instead, it is necessary to use the move operation:
+```typescript
+array.moveToStart(2);
+```
+Work is underway to address this lack of flexibility.
+
+### Replacing Items
+
+When dealing with plain JavaScript arrays, it is possible to replace items.
+For example, in array  `[A, B, C]`,
+the item B can be replaced with item X with [the `splice` method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice):
+```typescript
+array.splice(1, 1, X);
+```
+...or simply by using the `=` operator:
+```typescript
+array[1] = X;
+```
+
+As of October 2024, SharedTree arrays do not support either of these approaches.
+The closest alternative is to remove and insert items in two separate calls:
+```typescript
+array.removeAt(1);
+array.insertAt(1, X);
+```
+
+Note that this approach may not yield ideal merge outcomes when it comes to concurrent insertions.
+
+Example:
+* Starting state: `["gold", "bronze"]`
+* User 1: replace "gold" and "bronze" with "1st place" and "3rd place":
+  * `removeRange(0, 2)`
+  * `insertAt(0, "1st place", "3rd place")`
+* User 2: insert "2nd place" between "gold" and "bronze":
+  * `insertAt(1, "2nd place")`
+* Merge outcome: `["1st place", "3rd place", "2nd place"]`
+
+This outcome is not consistent with the idea of replacement
+which would have yielded `["1st place", "2nd place", "3rd place"]` instead.
+This is because removing and inserting does not update the original items in place.
+So we effectively end up with `["1st place", "3rd place", `~~`"gold"`~~`, "2nd place", `~~`"bronze"`~~`]`.
+
+If in-place replacement is critical to you application's needs,
+please reach out to the Fluid team.

package/docs/user-facing/map-merge-semantics.md

@@ -0,0 +1,128 @@
+# Merge Semantics of Edits on Map Nodes
+
+This document describes the semantics of edits that can be performed on map nodes.
+
+Target audience: `SharedTree` users and maintainers.
+
+> While this document is self-contained, we recommend reading about [SharedTree's approach to merge semantics](merge-semantics) first.
+
+Each edit's merge semantics are defined in terms of the edit's preconditions and postconditions.
+A precondition defines a requirement that must be met for the edit to be valid.
+A postcondition defines a guarantee that is made about the effect of the edit.
+(Invalid edits are ignored along with all other edits in the same transaction, and postconditions do not hold).
+
+## `set(key: string, value: T): void`
+
+Updates the value associated with the given key.
+
+Examples:
+```typescript
+users.set("bob", new User({ id: "bob", email: "bob@contoso.com" });
+```
+
+```typescript
+partCounts.set("bolts", 42);
+```
+
+Preconditions:
+* There is no concurrent schema change edit that is sequenced before the `set` edit.
+* The value on the right side of the `=` operator must have status `TreeStatus.New` or be a primitive.
+  (This precondition will be removed soon)
+
+Postconditions:
+* The given value is now associated with the given key.
+* The value (if any) that was associated with the given key immediately prior to the application of the edit is removed (its status becomes `TreeStatus.Removed`).
+
+## `delete(key: string): void`
+
+Clears any value associated with the given key.
+
+```typescript
+users.delete("bob");
+```
+
+Preconditions:
+* There is no concurrent schema change edit that is sequenced before the `delete` edit.
+
+Postconditions:
+* There is no longer any value associated with the given key.
+  The value (if any) that was associated with the given key immediately prior to the application of the edit is removed (its status becomes `TreeStatus.Removed`).
+  Note: this will remove whatever value is associated with the key,
+  even if that value was changed by concurrent edits that were sequenced earlier.
+
+Removed items are saved internally for a time in case they need to be restored as a result of an undo operation.
+Changes made to them will apply despite their removed status.
+
+## Additional Notes
+
+### Operations on Removed Maps
+
+All of the above operations are effective even when the targeted map has been moved or removed.
+
+### Last-Write-Wins Semantics
+
+If multiple edits concurrently set the same key, then the key's final value will be that of the edit that is sequenced last.
+In other words, the `set` operation has last-write-wins semantics.
+
+Note that this means one user may overwrite a value set by another user without realizing it.
+This is identical to the semantics of the `=` operator on object nodes.
+Refer to its [Last-Write-Wins Semantics section](./object-merge-semantics.md#last-write-wins-semantics) for more details.
+
+### Delete Clears Whichever Value is Present
+
+If user A calls `map.set("key", 42)` and user B concurrently calls `map.delete("key", 42)` on same map node,
+then the outcome depends on the arbitrary ordering that is imposed by the sequencing service:
+If the `delete` call is ordered before the `set` call, then the `set` will win out, setting the new associated value for that key.
+If the `set` call is ordered before the `delete` call, then the `delete` will win out, clearing the associated value for that key.
+
+This last point means that one user may end up deleting a value they have never seen.
+Consider the following scenario:
+* Starting state: `map.get("key")` is equal to `"foo"`
+* Client A wants to replace the value `"foo"` with the value `"bar"` so they call `map.set("key", "bar")`.
+* Client B wants to delete the value `"foo"` so they call `map.delete("key")`.
+
+If these two edits are made concurrently,
+and if client A's edit is sequenced before client B's edit,
+then client B's edit will end up removing the value `"bar"`.
+This is typically acceptable, but in cases where it proves problematic,
+it's possible to put the `delete` operation in a transaction with a constraint that ensures the value to be deleted is still in the tree.
+
+### Removing and Re-inserting Nodes
+
+When dealing with plain JavaScript maps,
+it is possible to move items around by removing them and adding them back in.
+For example, if some node N needs to be moved from `mapA` to `mapB`,
+that can accomplished with the following operations:
+```typescript
+const N = mapA.get(key);
+mapA.delete(key); // Remove node N from mapA
+mapB.set(key, N); // Insert node N into mapB
+```
+
+Similarly, plain JavaScript maps allow moving a value from one key to another within the same map:
+```typescript
+const N = mapA.get("foo");
+mapA.delete("foo"); // Remove node N from mapA/key "foo"
+mapA.set("bar", N); // Insert node N into mapA/key "bar"
+```
+
+As of October 2024, SharedTree maps do not support these patterns because it would require (re)inserting node N, which has previously been inserted.
+Note that even without this restriction, the above would not perform the desired change if some other user concurrently moved N from `mapA` to some other `mapC`.
+If that were the case...
+* Node N may no longer be in `mapA` by the time the edit `mapA.delete(key)` is applied.
+  At best that edit would have no effect, and at worst it may inadvertently remove some other node.
+* Node N may still be in `mapC` by the time the edit `mapB.set(key, N)` is applied.
+  If so, this would lead to an error since a single node cannot reside in multiple maps at the same time.
+  (This would violate the requirement that the document remains tree-shaped).
+
+Work is underway to address this lack of flexibility.
+
+### Clearing The Map
+
+As of October 2024, there is no support for clearing the whole map in one operation.
+If you find yourself wishing for such an operation, please reach out to the Fluid team.
+
+Note that one client can, in a transaction, iterate through all existing key and use the `delete` operation on each of them.
+This does not however guarantee that the map will be empty after the transaction is applied
+because other users may have concurrently added entries to new keys.
+This approach is also much less efficient than a `clear` operation would be since it needs to transmit the set of existing key over the network.

package/docs/user-facing/merge-semantics.md

@@ -358,7 +358,7 @@ By contrast, `SharedTree`'s move semantics ensure that Bob's edit will be visibl
 In choosing the merge semantics of the set of edits initially supported by `SharedTree`,
 we have strived to keep the preconditions of those edits minimal.
 At this time, with the exception of [schema changes](#schema-changes), which have more preconditions,
-all supported edits have the same single precondition:
+most supported edits have the same single precondition:
 the document schema must not have been concurrently changed.
 
 As illustrated [above](#preconditions),
@@ -428,7 +428,7 @@ A conditional postcondition is a postcondition of the form "If \<condition\> the
 (with any number of "else if" branches).
 For example, a remove edit that was designed not to affect concurrently moved nodes would be characterized as
 "If the node was concurrently moved then the node is unaffected, otherwise, the node is removed".
-After an edit with such a conditional postcondition is applied, it is not certain whether the targeted no will be removed or not.
+After an edit with such a conditional postcondition is applied, it is not certain whether the targeted node will be removed or not.
 
 None of `SharedTree`'s currently supported edits have conditional postconditions.
 This means that every edit, so long as its preconditions are met, is guaranteed to always have the same effect.
@@ -526,4 +526,8 @@ The merge semantics will be improved in the future to be less conservative.
 
 ## Merge Semantics by Node Kind
 
-TODO: add a separate document for each node kind and link to them from here.
+For specifics on the merge semantics of individual edits operations for each node type, 
+
+[Object Node](object-merge-semantics.md)
+[Map Node](map-merge-semantics.md)
+[Array Node](array-merge-semantics.md)