@fluidframework/tree 2.73.0 → 2.74.0-368706

package/lib/feature-libraries/default-schema/defaultEditBuilder.d.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 import type { ICodecFamily } from "../../codec/index.js";
-import { type ChangeEncodingContext, type ChangeFamily, type ChangeFamilyEditor, type ChangeRebaser, type DeltaDetachedNodeId, type DeltaRoot, type FieldUpPath, type NormalizedFieldUpPath, type NormalizedUpPath, type RevisionTag, type TaggedChange, type TreeChunk, type UpPath } from "../../core/index.js";
+import { type ChangeAtomId, type ChangeEncodingContext, type ChangeFamily, type ChangeFamilyEditor, type ChangeRebaser, type ChangesetLocalId, type DeltaDetachedNodeId, type DeltaRoot, type EditorOptions, type NormalizedFieldUpPath, type NormalizedUpPath, type RevisionTag, type TaggedChange, type TreeChunk } from "../../core/index.js";
 import { type ModularChangeset } from "../modular-schema/index.js";
 export type DefaultChangeset = ModularChangeset;
 /**
@@ -11,12 +11,12 @@ export type DefaultChangeset = ModularChangeset;
  *
  * @sealed
  */
-export declare class DefaultChangeFamily implements ChangeFamily<DefaultEditBuilder, DefaultChangeset> {
+export declare class DefaultChangeFamily implements ChangeFamily<IdBasedChangeFamilyDataEditor, DefaultChangeset> {
     private readonly modularFamily;
     constructor(codecs: ICodecFamily<ModularChangeset, ChangeEncodingContext>);
     get rebaser(): ChangeRebaser<DefaultChangeset>;
     get codecs(): ICodecFamily<DefaultChangeset, ChangeEncodingContext>;
-    buildEditor(mintRevisionTag: () => RevisionTag, changeReceiver: (change: TaggedChange<DefaultChangeset>) => void): DefaultEditBuilder;
+    buildEditor(mintRevisionTag: () => RevisionTag, changeReceiver: (change: TaggedChange<DefaultChangeset>) => void, options?: EditorOptions): IdBasedChangeFamilyDataEditor;
 }
 /**
  * @param change - The change to convert into a delta.
@@ -37,8 +37,13 @@ export declare function intoDelta(taggedChange: TaggedChange<ModularChangeset>):
  * @param change - The change to be applied.
  */
 export declare function relevantRemovedRoots(change: ModularChangeset): Iterable<DeltaDetachedNodeId>;
+export type DetachedRootIds = readonly DetachedRootIdRange[];
+export interface DetachedRootIdRange {
+    readonly first: ChangeAtomId;
+    readonly count: number;
+}
 /**
- * Default editor for transactional tree data changes.
+ * Default editor for tree data changes.
  * @privateRemarks
  * When taking into account not just the content of the tree,
  * but also how the merge identities (and thus anchors, flex-tree and simple-tree nodes) of nodes before and after the edits correspond,
@@ -54,21 +59,45 @@ export declare function relevantRemovedRoots(change: ModularChangeset): Iterable
  * If/when such a mechanism becomes available, an evaluation should be done to determine if any existing editing operations should be changed to leverage it
  * (Possibly by adding opt ins at the view schema layer).
  */
-export interface IDefaultEditBuilder<TContent = TreeChunk> {
+export interface DataEditor<TContent, TDetachedRoot, TDetachedRoots> {
+    /**
+     * Moves a subsequence from one sequence field to another sequence field.
+     *
+     * Note that the `destinationIndex` is interpreted based on the state of the sequence *before* the move operation.
+     * For example, `move(field, 0, 1, field, 2)` changes `[A, B, C]` to `[B, A, C]`.
+     */
+    move(sourceField: NormalizedFieldUpPath, sourceIndex: number, count: number, destinationField: NormalizedFieldUpPath, destinationIndex: number): void;
+    /**
+     * Add a constraint that the node at the given path must exist.
+     * @param path - The path to the node that must exist.
+     */
+    addNodeExistsConstraint(path: NormalizedUpPath): void;
+    /**
+     * Add a constraint that the node at the given path must exist when reverting a change.
+     * @param path - The path to the node that must exist when reverting a change.
+     */
+    addNodeExistsConstraintOnRevert(path: NormalizedUpPath): void;
+    /**
+     * Builds the detached roots for the given content.
+     * @param content - The content to be built into detached nodes.
+     *
+     * Requires SharedTreeFormatVersion.vDetachedRoots or later.
+     */
+    buildRoots(content: TContent): TDetachedRoots;
     /**
      * @param field - the value field which is being edited under the parent node
      * @returns An object with methods to edit the given field of the given parent.
      * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
      * is bounded by the lifetime of this edit builder.
      */
-    valueField(field: NormalizedFieldUpPath): ValueFieldEditBuilder<TContent>;
+    valueField(field: NormalizedFieldUpPath): RequiredFieldEditor<TContent, TDetachedRoot>;
     /**
      * @param field - the optional field which is being edited under the parent node
      * @returns An object with methods to edit the given field of the given parent.
      * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
      * is bounded by the lifetime of this edit builder.
      */
-    optionalField(field: NormalizedFieldUpPath): OptionalFieldEditBuilder<TContent>;
+    optionalField(field: NormalizedFieldUpPath): OptionalFieldEditor<TContent, TDetachedRoot>;
     /**
      * @param field - the sequence field which is being edited under the parent node
      *
@@ -76,65 +105,84 @@ export interface IDefaultEditBuilder<TContent = TreeChunk> {
      * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
      * is bounded by the lifetime of this edit builder.
      */
-    sequenceField(field: NormalizedFieldUpPath): SequenceFieldEditBuilder<TContent>;
-    /**
-     * Moves a subsequence from one sequence field to another sequence field.
-     *
-     * Note that the `destinationIndex` is interpreted based on the state of the sequence *before* the move operation.
-     * For example, `move(field, 0, 1, field, 2)` changes `[A, B, C]` to `[B, A, C]`.
-     */
-    move(sourceField: NormalizedFieldUpPath, sourceIndex: number, count: number, destinationField: NormalizedFieldUpPath, destinationIndex: number): void;
-    /**
-     * Add a constraint that the node at the given path must exist.
-     * @param path - The path to the node that must exist.
-     */
-    addNodeExistsConstraint(path: NormalizedUpPath): void;
-    /**
-     * Add a constraint that the node at the given path must exist when reverting a change.
-     * @param path - The path to the node that must exist when reverting a change.
-     */
-    addNodeExistsConstraintOnRevert(path: NormalizedUpPath): void;
+    sequenceField(field: NormalizedFieldUpPath): SequenceFieldEditor<TContent, TDetachedRoots>;
 }
+export type IdBasedChangeFamilyDataEditor = ChangeFamilyEditor & DataEditor<TreeChunk, ChangeAtomId, DetachedRootIds>;
+export declare function offsetChangesetLocalId(id: ChangesetLocalId, offset: number): ChangesetLocalId;
+export declare function subtractChangesetLocalId(a: ChangesetLocalId, b: ChangesetLocalId): number;
 /**
- * Implementation of {@link IDefaultEditBuilder} based on the default set of supported field kinds.
+ * Implementation of {@link IdBasedChangeFamilyDataEditor} based on the default set of supported field kinds.
  * @sealed
  */
-export declare class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuilder {
+export declare class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
     private readonly mintRevisionTag;
+    private readonly options;
     private readonly modularBuilder;
-    constructor(family: ChangeFamily<ChangeFamilyEditor, DefaultChangeset>, mintRevisionTag: () => RevisionTag, changeReceiver: (change: TaggedChange<DefaultChangeset>) => void);
+    private readonly nodesWithoutCells;
+    constructor(family: ChangeFamily<ChangeFamilyEditor, DefaultChangeset>, mintRevisionTag: () => RevisionTag, changeReceiver: (change: TaggedChange<DefaultChangeset>) => void, options?: EditorOptions);
     enterTransaction(): void;
     exitTransaction(): void;
-    addNodeExistsConstraint(path: UpPath): void;
-    addNodeExistsConstraintOnRevert(path: UpPath): void;
-    valueField(field: FieldUpPath): ValueFieldEditBuilder<TreeChunk>;
-    optionalField(field: FieldUpPath): OptionalFieldEditBuilder<TreeChunk>;
-    move(sourceField: FieldUpPath, sourceIndex: number, count: number, destinationField: FieldUpPath, destIndex: number): void;
-    sequenceField(field: FieldUpPath): SequenceFieldEditBuilder<TreeChunk>;
+    addNodeExistsConstraint(path: NormalizedUpPath): void;
+    addNodeExistsConstraintOnRevert(path: NormalizedUpPath): void;
+    buildRoots(content: TreeChunk): DetachedRootIds;
+    valueField(field: NormalizedFieldUpPath): RequiredFieldEditor<TreeChunk, ChangeAtomId>;
+    optionalField(field: NormalizedFieldUpPath): OptionalFieldEditor<TreeChunk, ChangeAtomId>;
+    move(sourceField: NormalizedFieldUpPath, sourceIndex: number, count: number, destinationField: NormalizedFieldUpPath, destIndex: number): void;
+    sequenceField(field: NormalizedFieldUpPath): SequenceFieldEditor<TreeChunk, DetachedRootIds>;
 }
-export interface ValueFieldEditBuilder<TContent> {
+export interface RequiredFieldEditor<TContent, TDetachedRoot> {
+    /**
+     * Issues a change which replaces the content of the field with the given detached node.
+     * @param content - The content to be attached in the field in the given order.
+     * Must represent a single detached node.
+     * Must have been created in the same JS turn.
+     *
+     * Requires SharedTreeFormatVersion.vDetachedRoots or later.
+     */
+    attach(content: TDetachedRoot): void;
     /**
-     * Issues a change which replaces the current newContent of the field with `newContent`.
+     * Issues a change which replaces the content of the field with `newContent`.
      * @param newContent - the new content for the field.
      */
     set(newContent: TContent): void;
 }
-export interface OptionalFieldEditBuilder<TContent> {
+export interface OptionalFieldEditor<TContent, TDetachedRoots> {
+    /**
+     * Issues a change which replaces the content of the field with the given detached node.
+     * @param content - The content to be attached in the field in the given order.
+     * Must represent a single detached node.
+     *
+     * Requires SharedTreeFormatVersion.vDetachedRoots or later.
+     */
+    attach(content: TDetachedRoots | undefined, wasEmpty: boolean): void;
+    /**
+     * Issues a change which clears content of the field.
+     * @param wasEmpty - whether the field is empty when creating this change
+     */
+    clear(wasEmpty: boolean): void;
     /**
-     * Issues a change which replaces the current newContent of the field with `newContent`.
+     * Issues a change which replaces the content of the field with `newContent`
      * @param newContent - the new content for the field.
-     * @param wasEmpty - whether the field is empty when creating this change.
+     * @param wasEmpty - whether the field is empty when creating this change
      */
     set(newContent: TContent | undefined, wasEmpty: boolean): void;
 }
 /**
- * Edit builder for the sequence field kind.
+ * Editor for the sequence field kind.
  */
-export interface SequenceFieldEditBuilder<TContent, TRemoved = void> {
+export interface SequenceFieldEditor<TContent, TDetachedRoots, TRemoved = void> {
+    /**
+     * Issues a change which attaches a sequence of detached nodes at the given `index`.
+     * @param index - The index at which to attach the detached nodes.
+     * @param detachedContent - The content to be attached in the field in the given order. Each node must be detached.
+     *
+     * Requires SharedTreeFormatVersion.vDetachedRoots or later.
+     */
+    attach(index: number, detachedContent: TDetachedRoots): void;
     /**
      * Issues a change which inserts the `newContent` at the given `index`.
      * @param index - the index at which to insert the `newContent`.
-     * @param newContent - the new content to be inserted in the field. Cursor can be in either Field or Node mode.
+     * @param newContent - the new content to be inserted in the field.
      */
     insert(index: number, newContent: TContent): void;
     /**

package/lib/feature-libraries/default-schema/defaultEditBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaultEditBuilder.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/default-schema/defaultEditBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"defaultEditBuilder.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/default-schema/defaultEditBuilder.ts"],"names":[],"mappings":"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"}

package/lib/feature-libraries/default-schema/defaultEditBuilder.js

@@ -4,8 +4,8 @@
  */
 import { assert, oob } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { compareFieldUpPaths, topDownPath, } from "../../core/index.js";
-import { brand } from "../../util/index.js";
+import { compareFieldUpPaths, getDetachedFieldContainingFieldPath, rootField, topDownPath, } from "../../core/index.js";
+import { brand, RangeMap } from "../../util/index.js";
 import { ModularChangeFamily, ModularEditBuilder, intoDelta as intoModularDelta, relevantRemovedRoots as relevantModularRemovedRoots, } from "../modular-schema/index.js";
 import { fieldKinds, optional, sequence, required as valueFieldKind, } from "./defaultFieldKinds.js";
 /**
@@ -23,8 +23,8 @@ export class DefaultChangeFamily {
     get codecs() {
         return this.modularFamily.codecs;
     }
-    buildEditor(mintRevisionTag, changeReceiver) {
-        return new DefaultEditBuilder(this, mintRevisionTag, changeReceiver);
+    buildEditor(mintRevisionTag, changeReceiver, options) {
+        return new DefaultIdBasedDataEditor(this, mintRevisionTag, changeReceiver, options);
     }
 }
 /**
@@ -50,71 +50,158 @@ export function intoDelta(taggedChange) {
 export function relevantRemovedRoots(change) {
     return relevantModularRemovedRoots(change, fieldKinds);
 }
+export function offsetChangesetLocalId(id, offset) {
+    return brand(id + offset);
+}
+export function subtractChangesetLocalId(a, b) {
+    return a - b;
+}
 /**
- * Implementation of {@link IDefaultEditBuilder} based on the default set of supported field kinds.
+ * Implementation of {@link IdBasedChangeFamilyDataEditor} based on the default set of supported field kinds.
  * @sealed
  */
-export class DefaultEditBuilder {
-    constructor(family, mintRevisionTag, changeReceiver) {
+export class DefaultIdBasedDataEditor {
+    constructor(family, mintRevisionTag, changeReceiver, options = { canMakeDetachedRootEdits: false }) {
         this.mintRevisionTag = mintRevisionTag;
+        this.options = options;
+        this.nodesWithoutCells = new RangeMap(offsetChangesetLocalId, subtractChangesetLocalId);
         this.modularBuilder = new ModularEditBuilder(family, fieldKinds, changeReceiver);
     }
     enterTransaction() {
+        if (this.modularBuilder.isInTransaction() === false) {
+            this.nodesWithoutCells.clear();
+        }
         this.modularBuilder.enterTransaction();
     }
     exitTransaction() {
         this.modularBuilder.exitTransaction();
+        if (this.modularBuilder.isInTransaction() === false) {
+            this.nodesWithoutCells.clear();
+        }
     }
     addNodeExistsConstraint(path) {
+        enforceEditsToDetachedTreesOptions({ parent: path.parent, field: path.parentField }, this.options);
         this.modularBuilder.addNodeExistsConstraint(path, this.mintRevisionTag());
     }
     addNodeExistsConstraintOnRevert(path) {
+        enforceEditsToDetachedTreesOptions({ parent: path.parent, field: path.parentField }, this.options);
         this.modularBuilder.addNodeExistsConstraintOnRevert(path, this.mintRevisionTag());
     }
+    buildRoots(content) {
+        const detachedRoots = [];
+        const count = content.topLevelLength;
+        if (count > 0) {
+            const buildRevision = this.mintRevisionTag();
+            const buildId = {
+                localId: this.modularBuilder.generateId(count),
+                revision: buildRevision,
+            };
+            const build = this.modularBuilder.buildTrees(buildId.localId, content, buildRevision);
+            this.modularBuilder.submitChanges([build], buildRevision);
+            detachedRoots.push({ first: buildId, count });
+            this.nodesWithoutCells.set(buildId.localId, count, true);
+        }
+        return detachedRoots;
+    }
     valueField(field) {
+        enforceEditsToDetachedTreesOptions(field, this.options);
+        const makeAttachEditDescription = (fill, revision) => {
+            const detachLocalId = this.modularBuilder.generateId();
+            const detach = { localId: detachLocalId, revision };
+            const change = valueFieldKind.changeHandler.editor.set({ fill, detach });
+            return {
+                type: "field",
+                field,
+                fieldKind: valueFieldKind.identifier,
+                change: brand(change),
+                revision,
+            };
+        };
         return {
             set: (newContent) => {
-                assert(newContent.topLevelLength === 1, 0xc12 /* Value fields should have a single top level node */);
+                assert(newContent.topLevelLength === 1, "Expected exactly one node");
                 const revision = this.mintRevisionTag();
-                const fill = { localId: this.modularBuilder.generateId(), revision };
-                const detach = { localId: this.modularBuilder.generateId(), revision };
-                const build = this.modularBuilder.buildTrees(fill.localId, newContent, revision);
-                const change = brand(valueFieldKind.changeHandler.editor.set({
-                    fill,
-                    detach,
-                }));
-                const edit = {
-                    type: "field",
-                    field,
-                    fieldKind: valueFieldKind.identifier,
-                    change,
-                    revision,
-                };
-                this.modularBuilder.submitChanges([build, edit], revision);
+                const buildLocalId = this.modularBuilder.generateId();
+                const buildId = { localId: buildLocalId, revision };
+                const build = this.modularBuilder.buildTrees(buildLocalId, newContent, revision);
+                const attach = makeAttachEditDescription(buildId, revision);
+                this.modularBuilder.submitChanges([build, attach], revision);
+            },
+            attach: (newContent) => {
+                const isWithoutCell = this.nodesWithoutCells.delete(newContent.localId, 1) === 1;
+                if (!isWithoutCell) {
+                    throw new UsageError("A hydrated node that has been attached before cannot be attached into an object's required field. Assign new content to the field instead.");
+                }
+                const revision = this.mintRevisionTag();
+                const attach = makeAttachEditDescription(newContent, revision);
+                this.modularBuilder.submitChanges([attach], revision);
             },
         };
     }
     optionalField(field) {
-        return {
+        enforceEditsToDetachedTreesOptions(field, this.options);
+        const makeAttachEditDescription = (fill, revision, wasEmpty) => {
+            const detachLocalId = this.modularBuilder.generateId();
+            const detach = { localId: detachLocalId, revision };
+            const change = optional.changeHandler.editor.set(wasEmpty, { fill, detach });
+            return {
+                type: "field",
+                field,
+                fieldKind: optional.identifier,
+                change: brand(change),
+                revision,
+            };
+        };
+        const editBuilder = {
             set: (newContent, wasEmpty) => {
-                // The choice to ban empty chunks here instead of treating them as a clear is a subjective choice made to err of the side of more explicitness and stricter validation.
-                assert(newContent === undefined || newContent.topLevelLength === 1, 0xc13 /* optional fields should have a single top level node, or undefined */);
-                const edits = [];
-                let optionalChange;
+                if (newContent === undefined) {
+                    editBuilder.clear(wasEmpty);
+                    return;
+                }
+                assert(newContent.topLevelLength === 1, "Expected exactly one node");
                 const revision = this.mintRevisionTag();
-                const detach = { localId: this.modularBuilder.generateId(), revision };
-                if (newContent !== undefined) {
-                    const fill = { localId: this.modularBuilder.generateId(), revision };
-                    const build = this.modularBuilder.buildTrees(fill.localId, newContent, revision);
-                    edits.push(build);
-                    optionalChange = optional.changeHandler.editor.set(wasEmpty, {
-                        fill,
-                        detach,
-                    });
+                const buildLocalId = this.modularBuilder.generateId();
+                const buildId = { localId: buildLocalId, revision };
+                const build = this.modularBuilder.buildTrees(buildLocalId, newContent, revision);
+                const attach = makeAttachEditDescription(buildId, revision, wasEmpty);
+                this.modularBuilder.submitChanges([build, attach], revision);
+            },
+            attach: (content, wasEmpty) => {
+                if (content === undefined) {
+                    editBuilder.clear(wasEmpty);
+                    return;
+                }
+                const isWithoutCell = this.nodesWithoutCells.delete(content.localId, 1) === 1;
+                if (!isWithoutCell && this.options.canMakeDetachedRootEdits !== true) {
+                    throw new UsageError(`Attach edits require a minimum version for collaboration >= TBD.`);
+                }
+                const revision = this.mintRevisionTag();
+                const edits = [];
+                let stableSrcId;
+                if (isWithoutCell) {
+                    stableSrcId = content;
                 }
                 else {
-                    optionalChange = optional.changeHandler.editor.clear(wasEmpty, detach);
+                    // If the node has an associated cell, then it may be concurrently moved to another location.
+                    // We use a rename to ensure that the node will be moved to a specific grave before the attach.
+                    stableSrcId = { localId: this.modularBuilder.generateId(), revision };
+                    const rename = {
+                        type: "global",
+                        revision,
+                        renames: [
+                            { count: 1, oldId: content, newId: stableSrcId, detachLocation: undefined },
+                        ],
+                    };
+                    edits.push(rename);
                 }
+                const attach = makeAttachEditDescription(stableSrcId, revision, wasEmpty);
+                edits.push(attach);
+                this.modularBuilder.submitChanges(edits, revision);
+            },
+            clear: (wasEmpty) => {
+                const revision = this.mintRevisionTag();
+                const detach = { localId: this.modularBuilder.generateId(), revision };
+                const optionalChange = optional.changeHandler.editor.clear(wasEmpty, detach);
                 const change = brand(optionalChange);
                 const edit = {
                     type: "field",
@@ -123,10 +210,10 @@ export class DefaultEditBuilder {
                     change,
                     revision,
                 };
-                edits.push(edit);
-                this.modularBuilder.submitChanges(edits, revision);
+                this.modularBuilder.submitChanges([edit], revision);
             },
         };
+        return editBuilder;
     }
     move(sourceField, sourceIndex, count, destinationField, destIndex) {
         if (count === 0) {
@@ -135,6 +222,8 @@ export class DefaultEditBuilder {
         else if (count < 0 || !Number.isSafeInteger(count)) {
             throw new UsageError(`Expected non-negative integer count, got ${count}.`);
         }
+        enforceEditsToDetachedTreesOptions(sourceField, this.options);
+        enforceEditsToDetachedTreesOptions(destinationField, this.options);
         const revision = this.mintRevisionTag();
         const detachCellId = this.modularBuilder.generateId(count);
         const attachCellId = { localId: this.modularBuilder.generateId(count), revision };
@@ -147,13 +236,13 @@ export class DefaultEditBuilder {
             const attachPath = topDownPath(destinationField.parent);
             const sharedDepth = getSharedPrefixLength(detachPath, attachPath);
             let adjustedAttachField = destinationField;
-            // After the above loop, `sharedDepth` is the number of elements, starting from the root,
-            // that both paths have in common.
+            // `sharedDepth` is the number of elements, starting from the root, that both paths have in common.
             if (sharedDepth === detachPath.length) {
-                const attachField = attachPath[sharedDepth]?.parentField ?? destinationField.field;
+                const lowestCommonAncestor = attachPath[sharedDepth];
+                const attachField = lowestCommonAncestor?.parentField ?? destinationField.field;
                 if (attachField === sourceField.field) {
                     // The detach occurs in an ancestor field of the field where the attach occurs.
-                    let attachAncestorIndex = attachPath[sharedDepth]?.parentIndex ?? sourceIndex;
+                    const attachAncestorIndex = lowestCommonAncestor?.parentIndex ?? destIndex;
                     if (attachAncestorIndex < sourceIndex) {
                         // The attach path runs through a node located before the detached nodes.
                         // No need to adjust the attach path.
@@ -162,14 +251,18 @@ export class DefaultEditBuilder {
                         // The attach path runs through a node located after the detached nodes.
                         // adjust the index for the node at that depth of the path, so that it is interpreted correctly
                         // in the composition performed by `submitChanges`.
-                        attachAncestorIndex -= count;
-                        let parent = attachPath[sharedDepth - 1];
-                        const parentField = attachPath[sharedDepth] ?? oob();
-                        parent = {
-                            parent,
-                            parentIndex: attachAncestorIndex,
-                            parentField: parentField.parentField,
-                        };
+                        const adjustedAttachAncestorIndex = attachAncestorIndex - count;
+                        let parent = lowestCommonAncestor === undefined
+                            ? {
+                                parent: undefined,
+                                detachedNodeId: undefined,
+                                parentIndex: adjustedAttachAncestorIndex,
+                                parentField: destinationField.field,
+                            }
+                            : {
+                                ...lowestCommonAncestor,
+                                parentIndex: adjustedAttachAncestorIndex,
+                            };
                         for (let i = sharedDepth + 1; i < attachPath.length; i += 1) {
                             parent = {
                                 ...(attachPath[i] ?? oob()),
@@ -183,8 +276,8 @@ export class DefaultEditBuilder {
                     }
                 }
             }
-            const moveOut = sequence.changeHandler.editor.moveOut(sourceIndex, count, detachCellId, revision);
-            const moveIn = sequence.changeHandler.editor.moveIn(destIndex, count, detachCellId, attachCellId, revision);
+            const moveOut = sequence.changeHandler.editor.remove(sourceIndex, count, detachCellId, revision);
+            const moveIn = sequence.changeHandler.editor.insert(destIndex, count, attachCellId, revision, detachCellId);
             this.modularBuilder.submitChanges([
                 {
                     type: "field",
@@ -204,26 +297,87 @@ export class DefaultEditBuilder {
         }
     }
     sequenceField(field) {
-        return {
+        enforceEditsToDetachedTreesOptions(field, this.options);
+        const makeAttachEditDescription = (index, { first, count }, revision, areWithoutCells) => {
+            const edits = [];
+            // If the nodes have never been attached in cell, then we must use a cell ID that matches the build ID.
+            // This ensures back-compatibility with the v1 ModularChangeFamily model which requires that every node be associated with cell
+            // by generating an insert whose destination cell is the cell associated with the build ID.
+            let stableSrcId;
+            if (areWithoutCells) {
+                stableSrcId = first;
+            }
+            else {
+                // If the node has an associated cell, then it may be concurrently moved to another location.
+                // We use a rename to ensure that the node will be moved to a specific grave before the attach.
+                stableSrcId = { localId: this.modularBuilder.generateId(count), revision };
+                const rename = {
+                    type: "global",
+                    revision,
+                    renames: [
+                        {
+                            count,
+                            oldId: first,
+                            newId: stableSrcId,
+                            detachLocation: undefined,
+                        },
+                    ],
+                };
+                edits.push(rename);
+            }
+            assert(stableSrcId.revision !== undefined, "Detached nodes ID must have a revision");
+            const change = sequence.changeHandler.editor.insert(index, count, stableSrcId, stableSrcId.revision, stableSrcId.localId);
+            const attach = {
+                type: "field",
+                field,
+                fieldKind: sequence.identifier,
+                change: brand(change),
+                revision,
+            };
+            edits.push(attach);
+            return edits;
+        };
+        const editBuilder = {
             insert: (index, content) => {
-                const length = content.topLevelLength;
-                if (length === 0) {
+                const count = content.topLevelLength;
+                if (count === 0) {
                     return;
                 }
                 const revision = this.mintRevisionTag();
-                const firstId = { localId: this.modularBuilder.generateId(length), revision };
-                const build = this.modularBuilder.buildTrees(firstId.localId, content, revision);
-                const change = brand(sequence.changeHandler.editor.insert(index, length, firstId, revision));
-                const attach = {
-                    type: "field",
-                    field,
-                    fieldKind: sequence.identifier,
-                    change,
-                    revision,
+                const buildLocalId = this.modularBuilder.generateId();
+                const build = this.modularBuilder.buildTrees(buildLocalId, content, revision);
+                const roots = {
+                    first: { localId: buildLocalId, revision },
+                    count,
                 };
-                // The changes have to be submitted together, otherwise they will be assigned different revisions,
-                // which will prevent the build ID and the insert ID from matching.
-                this.modularBuilder.submitChanges([build, attach], revision);
+                const attach = makeAttachEditDescription(index, roots, revision, true);
+                this.modularBuilder.submitChanges([build, ...attach], revision);
+            },
+            attach: (index, newContent) => {
+                const attachRevision = this.mintRevisionTag();
+                let areAllWithoutCells = true;
+                let insertOffset = 0;
+                const edits = [];
+                for (const range of newContent) {
+                    if (range.count === 0) {
+                        continue;
+                    }
+                    const countWithoutCells = this.nodesWithoutCells.delete(range.first.localId, range.count);
+                    assert(countWithoutCells === 0 || countWithoutCells === range.count, "All detached roots within the same ID range must either all have or all not have a cell");
+                    const areWithoutCells = countWithoutCells === range.count;
+                    if (!areWithoutCells) {
+                        areAllWithoutCells = false;
+                    }
+                    const renameAndAttach = makeAttachEditDescription(index + insertOffset, range, attachRevision, areWithoutCells);
+                    edits.push(...renameAndAttach);
+                    insertOffset += range.count;
+                }
+                if (!areAllWithoutCells && this.options.canMakeDetachedRootEdits !== true) {
+                    throw new UsageError(`Attach edits require a minimum version for collaboration >= TBD.`);
+                }
+                if (edits.length > 0) {
+                    this.modularBuilder.submitChanges(edits, attachRevision);
+                }
             },
             remove: (index, count) => {
                 if (count === 0) {
@@ -235,6 +389,15 @@ export class DefaultEditBuilder {
                 this.modularBuilder.submitChange(field, sequence.identifier, change, revision);
             },
         };
+        return editBuilder;
+    }
+}
+function enforceEditsToDetachedTreesOptions(field, options) {
+    if (options.canMakeDetachedRootEdits !== true) {
+        const topField = getDetachedFieldContainingFieldPath(field);
+        if (topField !== rootField) {
+            throw new UsageError(`Edits and constraints on detached trees require a minimum version for collaboration >= TBD.`);
+        }
     }
 }
 /**