@fluidframework/tree 2.74.0-365691 → 2.74.0-368706

package/src/feature-libraries/default-schema/defaultEditBuilder.ts

@@ -13,8 +13,10 @@ import {
 	type ChangeFamily,
 	type ChangeFamilyEditor,
 	type ChangeRebaser,
+	type ChangesetLocalId,
 	type DeltaDetachedNodeId,
 	type DeltaRoot,
+	type EditorOptions,
 	type FieldUpPath,
 	type NormalizedFieldUpPath,
 	type NormalizedUpPath,
@@ -23,21 +25,22 @@ import {
 	type TreeChunk,
 	type UpPath,
 	compareFieldUpPaths,
+	getDetachedFieldContainingFieldPath,
+	rootField,
 	topDownPath,
 } from "../../core/index.js";
-import { brand } from "../../util/index.js";
+import { brand, RangeMap } from "../../util/index.js";
 import {
 	type EditDescription,
 	type FieldChangeset,
 	type FieldEditDescription,
+	type GlobalEditDescription,
 	ModularChangeFamily,
 	type ModularChangeset,
 	ModularEditBuilder,
 	intoDelta as intoModularDelta,
 	relevantRemovedRoots as relevantModularRemovedRoots,
 } from "../modular-schema/index.js";
-import type { OptionalChangeset } from "../optional-field/index.js";
-import type { CellId } from "../sequence-field/index.js";
 
 import {
 	fieldKinds,
@@ -45,6 +48,7 @@ import {
 	sequence,
 	required as valueFieldKind,
 } from "./defaultFieldKinds.js";
+import type { CellId } from "../sequence-field/index.js";
 
 export type DefaultChangeset = ModularChangeset;
 
@@ -54,7 +58,7 @@ export type DefaultChangeset = ModularChangeset;
  * @sealed
  */
 export class DefaultChangeFamily
-	implements ChangeFamily<DefaultEditBuilder, DefaultChangeset>
+	implements ChangeFamily<IdBasedChangeFamilyDataEditor, DefaultChangeset>
 {
 	private readonly modularFamily: ModularChangeFamily;
 
@@ -73,8 +77,9 @@ export class DefaultChangeFamily
 	public buildEditor(
 		mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<DefaultChangeset>) => void,
-	): DefaultEditBuilder {
-		return new DefaultEditBuilder(this, mintRevisionTag, changeReceiver);
+		options?: EditorOptions,
+	): IdBasedChangeFamilyDataEditor {
+		return new DefaultIdBasedDataEditor(this, mintRevisionTag, changeReceiver, options);
 	}
 }
 
@@ -103,8 +108,14 @@ export function relevantRemovedRoots(change: ModularChangeset): Iterable<DeltaDe
 	return relevantModularRemovedRoots(change, fieldKinds);
 }
 
+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,
@@ -120,32 +131,7 @@ export function relevantRemovedRoots(change: ModularChangeset): Iterable<DeltaDe
  * 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> {
-	/**
-	 * @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>;
-
-	/**
-	 * @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>;
-
-	/**
-	 * @param field - the sequence 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.
-	 */
-	sequenceField(field: NormalizedFieldUpPath): SequenceFieldEditBuilder<TContent>;
-
+export interface DataEditor<TContent, TDetachedRoot, TDetachedRoots> {
 	/**
 	 * Moves a subsequence from one sequence field to another sequence field.
 	 *
@@ -171,93 +157,236 @@ export interface IDefaultEditBuilder<TContent = TreeChunk> {
 	 * @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): 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): OptionalFieldEditor<TContent, TDetachedRoot>;
+
+	/**
+	 * @param field - the sequence 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.
+	 */
+	sequenceField(field: NormalizedFieldUpPath): SequenceFieldEditor<TContent, TDetachedRoots>;
+}
+
+export type IdBasedChangeFamilyDataEditor = ChangeFamilyEditor &
+	DataEditor<TreeChunk, ChangeAtomId, DetachedRootIds>;
+
+export function offsetChangesetLocalId(
+	id: ChangesetLocalId,
+	offset: number,
+): ChangesetLocalId {
+	return brand(id + offset);
+}
+
+export function subtractChangesetLocalId(a: ChangesetLocalId, b: ChangesetLocalId): number {
+	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 implements ChangeFamilyEditor, IDefaultEditBuilder {
+export class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
 	private readonly modularBuilder: ModularEditBuilder;
+	private readonly nodesWithoutCells: RangeMap<ChangesetLocalId, true> = new RangeMap(
+		offsetChangesetLocalId,
+		subtractChangesetLocalId,
+	);
 
 	public constructor(
 		family: ChangeFamily<ChangeFamilyEditor, DefaultChangeset>,
 		private readonly mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<DefaultChangeset>) => void,
+		private readonly options: EditorOptions = { canMakeDetachedRootEdits: false },
 	) {
 		this.modularBuilder = new ModularEditBuilder(family, fieldKinds, changeReceiver);
 	}
 
 	public enterTransaction(): void {
+		if (this.modularBuilder.isInTransaction() === false) {
+			this.nodesWithoutCells.clear();
+		}
 		this.modularBuilder.enterTransaction();
 	}
 	public exitTransaction(): void {
 		this.modularBuilder.exitTransaction();
+		if (this.modularBuilder.isInTransaction() === false) {
+			this.nodesWithoutCells.clear();
+		}
 	}
 
-	public addNodeExistsConstraint(path: UpPath): void {
+	public addNodeExistsConstraint(path: NormalizedUpPath): void {
+		enforceEditsToDetachedTreesOptions(
+			{ parent: path.parent, field: path.parentField },
+			this.options,
+		);
 		this.modularBuilder.addNodeExistsConstraint(path, this.mintRevisionTag());
 	}
 
-	public addNodeExistsConstraintOnRevert(path: UpPath): void {
+	public addNodeExistsConstraintOnRevert(path: NormalizedUpPath): void {
+		enforceEditsToDetachedTreesOptions(
+			{ parent: path.parent, field: path.parentField },
+			this.options,
+		);
 		this.modularBuilder.addNodeExistsConstraintOnRevert(path, this.mintRevisionTag());
 	}
 
-	public valueField(field: FieldUpPath): ValueFieldEditBuilder<TreeChunk> {
+	public buildRoots(content: TreeChunk): DetachedRootIds {
+		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;
+	}
+
+	public valueField(
+		field: NormalizedFieldUpPath,
+	): RequiredFieldEditor<TreeChunk, ChangeAtomId> {
+		enforceEditsToDetachedTreesOptions(field, this.options);
+		const makeAttachEditDescription = (
+			fill: ChangeAtomId,
+			revision: RevisionTag,
+		): FieldEditDescription => {
+			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: TreeChunk): void => {
-				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: ChangeAtomId = { localId: this.modularBuilder.generateId(), revision };
-				const detach: ChangeAtomId = { localId: this.modularBuilder.generateId(), revision };
-				const build = this.modularBuilder.buildTrees(fill.localId, newContent, revision);
-				const change: FieldChangeset = brand(
-					valueFieldKind.changeHandler.editor.set({
-						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);
+				this.modularBuilder.submitChanges([build, attach], revision);
+			},
 
-				const edit: FieldEditDescription = {
-					type: "field",
-					field,
-					fieldKind: valueFieldKind.identifier,
-					change,
-					revision,
-				};
-				this.modularBuilder.submitChanges([build, edit], revision);
+			attach: (newContent: ChangeAtomId): void => {
+				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);
 			},
 		};
 	}
 
-	public optionalField(field: FieldUpPath): OptionalFieldEditBuilder<TreeChunk> {
-		return {
+	public optionalField(
+		field: NormalizedFieldUpPath,
+	): OptionalFieldEditor<TreeChunk, ChangeAtomId> {
+		enforceEditsToDetachedTreesOptions(field, this.options);
+		const makeAttachEditDescription = (
+			fill: ChangeAtomId,
+			revision: RevisionTag,
+			wasEmpty: boolean,
+		): FieldEditDescription => {
+			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: TreeChunk | undefined, wasEmpty: boolean): void => {
-				// 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: EditDescription[] = [];
-				let optionalChange: OptionalChangeset;
+				if (newContent === undefined) {
+					editBuilder.clear(wasEmpty);
+					return;
+				}
+				assert(newContent.topLevelLength === 1, "Expected exactly one node");
 				const revision = this.mintRevisionTag();
-				const detach: ChangeAtomId = { localId: this.modularBuilder.generateId(), revision };
-				if (newContent !== undefined) {
-					const fill: ChangeAtomId = { 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: ChangeAtomId | undefined, wasEmpty: boolean): void => {
+				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: EditDescription[] = [];
+				let stableSrcId: ChangeAtomId;
+				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: GlobalEditDescription = {
+						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: boolean): void => {
+				const revision = this.mintRevisionTag();
+				const detach: ChangeAtomId = { localId: this.modularBuilder.generateId(), revision };
+				const optionalChange = optional.changeHandler.editor.clear(wasEmpty, detach);
 				const change: FieldChangeset = brand(optionalChange);
 				const edit: FieldEditDescription = {
 					type: "field",
@@ -266,18 +395,17 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 					change,
 					revision,
 				};
-				edits.push(edit);
-
-				this.modularBuilder.submitChanges(edits, revision);
+				this.modularBuilder.submitChanges([edit], revision);
 			},
 		};
+		return editBuilder;
 	}
 
 	public move(
-		sourceField: FieldUpPath,
+		sourceField: NormalizedFieldUpPath,
 		sourceIndex: number,
 		count: number,
-		destinationField: FieldUpPath,
+		destinationField: NormalizedFieldUpPath,
 		destIndex: number,
 	): void {
 		if (count === 0) {
@@ -285,6 +413,8 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		} 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: CellId = { localId: this.modularBuilder.generateId(count), revision };
@@ -308,13 +438,13 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 			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: NormalizedUpPath | undefined = 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.
@@ -322,14 +452,19 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 						// 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: UpPath | undefined = attachPath[sharedDepth - 1];
-						const parentField = attachPath[sharedDepth] ?? oob();
-						parent = {
-							parent,
-							parentIndex: attachAncestorIndex,
-							parentField: parentField.parentField,
-						};
+						const adjustedAttachAncestorIndex = attachAncestorIndex - count;
+						let parent: NormalizedUpPath =
+							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()),
@@ -344,19 +479,20 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 					}
 				}
 			}
-			const moveOut = sequence.changeHandler.editor.moveOut(
+			const moveOut = sequence.changeHandler.editor.remove(
 				sourceIndex,
 				count,
 				detachCellId,
 				revision,
 			);
-			const moveIn = sequence.changeHandler.editor.moveIn(
+			const moveIn = sequence.changeHandler.editor.insert(
 				destIndex,
 				count,
-				detachCellId,
 				attachCellId,
 				revision,
+				detachCellId,
 			);
+
 			this.modularBuilder.submitChanges(
 				[
 					{
@@ -379,30 +515,114 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		}
 	}
 
-	public sequenceField(field: FieldUpPath): SequenceFieldEditBuilder<TreeChunk> {
-		return {
+	public sequenceField(
+		field: NormalizedFieldUpPath,
+	): SequenceFieldEditor<TreeChunk, DetachedRootIds> {
+		enforceEditsToDetachedTreesOptions(field, this.options);
+		const makeAttachEditDescription = (
+			index: number,
+			{ first, count }: DetachedRootIdRange,
+			revision: RevisionTag,
+			areWithoutCells: boolean,
+		): EditDescription[] => {
+			const edits: EditDescription[] = [];
+			// 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: ChangeAtomId;
+			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: GlobalEditDescription = {
+					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: FieldEditDescription = {
+				type: "field",
+				field,
+				fieldKind: sequence.identifier,
+				change: brand(change),
+				revision,
+			};
+			edits.push(attach);
+			return edits;
+		};
+		const editBuilder = {
 			insert: (index: number, content: TreeChunk): void => {
-				const length = content.topLevelLength;
-				if (length === 0) {
+				const count = content.topLevelLength;
+				if (count === 0) {
 					return;
 				}
-
 				const revision = this.mintRevisionTag();
-				const firstId: CellId = { localId: this.modularBuilder.generateId(length), revision };
-				const build = this.modularBuilder.buildTrees(firstId.localId, content, revision);
-				const change: FieldChangeset = brand(
-					sequence.changeHandler.editor.insert(index, length, firstId, revision),
-				);
-				const attach: FieldEditDescription = {
-					type: "field",
-					field,
-					fieldKind: sequence.identifier,
-					change,
-					revision,
+				const buildLocalId = this.modularBuilder.generateId();
+				const build = this.modularBuilder.buildTrees(buildLocalId, content, revision);
+				const roots: DetachedRootIdRange = {
+					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: number, newContent: DetachedRootIds): void => {
+				const attachRevision = this.mintRevisionTag();
+				let areAllWithoutCells = true;
+				let insertOffset = 0;
+				const edits: EditDescription[] = [];
+				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: number, count: number): void => {
 				if (count === 0) {
@@ -416,34 +636,80 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 				this.modularBuilder.submitChange(field, sequence.identifier, change, revision);
 			},
 		};
+		return editBuilder;
 	}
 }
 
-export interface ValueFieldEditBuilder<TContent> {
+function enforceEditsToDetachedTreesOptions(field: FieldUpPath, options: EditorOptions): void {
+	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.`,
+			);
+		}
+	}
+}
+
+export interface RequiredFieldEditor<TContent, TDetachedRoot> {
 	/**
-	 * Issues a change which replaces the current newContent of the field with `newContent`.
+	 * 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 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;