@fluidframework/tree 2.90.0-378676 → 2.90.0

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

@@ -13,10 +13,9 @@ import {
 	type ChangeFamily,
 	type ChangeFamilyEditor,
 	type ChangeRebaser,
-	type ChangesetLocalId,
 	type DeltaDetachedNodeId,
 	type DeltaRoot,
-	type EditorOptions,
+	type FieldUpPath,
 	type NormalizedFieldUpPath,
 	type NormalizedUpPath,
 	type RevisionTag,
@@ -26,19 +25,18 @@ import {
 	compareFieldUpPaths,
 	topDownPath,
 } from "../../core/index.js";
-import { brand, RangeMap } from "../../util/index.js";
+import { brand } 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 { optional, required } from "../optional-field/index.js";
+import { optional, type OptionalChangeset, required } from "../optional-field/index.js";
 import { sequence, type CellId } from "../sequence-field/index.js";
 
 import { fieldKinds } from "./defaultFieldKinds.js";
@@ -51,7 +49,7 @@ export type DefaultChangeset = ModularChangeset;
  * @sealed
  */
 export class DefaultChangeFamily
-	implements ChangeFamily<IdBasedChangeFamilyDataEditor, DefaultChangeset>
+	implements ChangeFamily<DefaultEditBuilder, DefaultChangeset>
 {
 	private readonly modularFamily: ModularChangeFamily;
 
@@ -73,13 +71,11 @@ export class DefaultChangeFamily
 	public buildEditor(
 		mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<DefaultChangeset>) => void,
-		options?: EditorOptions,
-	): IdBasedChangeFamilyDataEditor {
-		return new DefaultIdBasedDataEditor(
+	): DefaultEditBuilder {
+		return new DefaultEditBuilder(
 			this,
 			mintRevisionTag,
 			changeReceiver,
-			options,
 			this.modularFamily.codecOptions,
 		);
 	}
@@ -110,14 +106,8 @@ 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 tree data changes.
+ * Default editor for transactional 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,
@@ -133,7 +123,32 @@ export interface DetachedRootIdRange {
  * 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 DataEditor<TContent, TDetachedRoot, TDetachedRoots> {
+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>;
+
 	/**
 	 * Moves a subsequence from one sequence field to another sequence field.
 	 *
@@ -169,71 +184,19 @@ export interface DataEditor<TContent, TDetachedRoot, TDetachedRoots> {
 	 * Add a constraint that, for the revert of this change to apply, the document must be in the same state immediately before the revert is applied as it was after this change was applied.
 	 */
 	addNoChangeConstraintOnRevert(): 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 IdBasedChangeFamilyDataEditor} based on the default set of supported field kinds.
+ * Implementation of {@link IDefaultEditBuilder} based on the default set of supported field kinds.
  * @sealed
  */
-export class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
+export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuilder {
 	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 = { enableDetachedRootEditing: false },
 		codecOptions: CodecWriteOptions,
 	) {
 		this.modularBuilder = new ModularEditBuilder(
@@ -241,28 +204,21 @@ export class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
 			fieldKinds,
 			changeReceiver,
 			codecOptions,
-			options,
 		);
 	}
 
 	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: NormalizedUpPath): void {
+	public addNodeExistsConstraint(path: UpPath): void {
 		this.modularBuilder.addNodeExistsConstraint(path, this.mintRevisionTag());
 	}
 
-	public addNodeExistsConstraintOnRevert(path: NormalizedUpPath): void {
+	public addNodeExistsConstraintOnRevert(path: UpPath): void {
 		this.modularBuilder.addNodeExistsConstraintOnRevert(path, this.mintRevisionTag());
 	}
 
@@ -274,136 +230,61 @@ export class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
 		this.modularBuilder.addNoChangeConstraintOnRevert(this.mintRevisionTag());
 	}
 
-	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> {
-		const makeAttachEditDescription = (
-			fill: ChangeAtomId,
-			revision: RevisionTag,
-		): FieldEditDescription => {
-			const detachLocalId = this.modularBuilder.generateId();
-			const detach = { localId: detachLocalId, revision };
-			const change = required.changeHandler.editor.set({ fill, detach });
-			return {
-				type: "field",
-				field,
-				fieldKind: required.identifier,
-				change: brand(change),
-				revision,
-			};
-		};
+	public valueField(field: FieldUpPath): ValueFieldEditBuilder<TreeChunk> {
 		return {
 			set: (newContent: TreeChunk): void => {
-				assert(newContent.topLevelLength === 1, "Expected exactly one node");
+				assert(
+					newContent.topLevelLength === 1,
+					0xc12 /* Value fields should have a single top level node */,
+				);
 				const revision = this.mintRevisionTag();
-				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 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(
+					required.changeHandler.editor.set({
+						fill,
+						detach,
+					}),
+				);
 
-			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);
+				const edit: FieldEditDescription = {
+					type: "field",
+					field,
+					fieldKind: required.identifier,
+					change,
+					revision,
+				};
+				this.modularBuilder.submitChanges([build, edit], revision);
 			},
 		};
 	}
 
-	public optionalField(
-		field: NormalizedFieldUpPath,
-	): OptionalFieldEditor<TreeChunk, ChangeAtomId> {
-		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 = {
+	public optionalField(field: FieldUpPath): OptionalFieldEditBuilder<TreeChunk> {
+		return {
 			set: (newContent: TreeChunk | undefined, wasEmpty: boolean): void => {
-				if (newContent === undefined) {
-					editBuilder.clear(wasEmpty);
-					return;
-				}
-				assert(newContent.topLevelLength === 1, "Expected exactly one node");
-				const revision = this.mintRevisionTag();
-				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.enableDetachedRootEditing !== true) {
-					throw new UsageError(
-						`Attach edits require a minimum version for collaboration >= TBD.`,
-					);
-				}
-				const revision = this.mintRevisionTag();
+				// 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 stableSrcId: ChangeAtomId;
-				if (isWithoutCell) {
-					stableSrcId = content;
-				} 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(), 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 => {
+				let optionalChange: OptionalChangeset;
 				const revision = this.mintRevisionTag();
 				const detach: ChangeAtomId = { localId: this.modularBuilder.generateId(), revision };
-				const optionalChange = optional.changeHandler.editor.clear(wasEmpty, detach);
+				if (newContent === undefined) {
+					optionalChange = optional.changeHandler.editor.clear(wasEmpty, detach);
+				} else {
+					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 change: FieldChangeset = brand(optionalChange);
 				const edit: FieldEditDescription = {
 					type: "field",
@@ -412,17 +293,18 @@ export class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
 					change,
 					revision,
 				};
-				this.modularBuilder.submitChanges([edit], revision);
+				edits.push(edit);
+
+				this.modularBuilder.submitChanges(edits, revision);
 			},
 		};
-		return editBuilder;
 	}
 
 	public move(
-		sourceField: NormalizedFieldUpPath,
+		sourceField: FieldUpPath,
 		sourceIndex: number,
 		count: number,
-		destinationField: NormalizedFieldUpPath,
+		destinationField: FieldUpPath,
 		destIndex: number,
 	): void {
 		if (count === 0) {
@@ -453,13 +335,13 @@ export class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
 			const attachPath = topDownPath(destinationField.parent);
 			const sharedDepth = getSharedPrefixLength(detachPath, attachPath);
 			let adjustedAttachField = destinationField;
-			// `sharedDepth` is the number of elements, starting from the root, that both paths have in common.
+			// After the above loop, `sharedDepth` is the number of elements, starting from the root,
+			// that both paths have in common.
 			if (sharedDepth === detachPath.length) {
-				const lowestCommonAncestor: NormalizedUpPath | undefined = attachPath[sharedDepth];
-				const attachField = lowestCommonAncestor?.parentField ?? destinationField.field;
+				const attachField = attachPath[sharedDepth]?.parentField ?? destinationField.field;
 				if (attachField === sourceField.field) {
 					// The detach occurs in an ancestor field of the field where the attach occurs.
-					const attachAncestorIndex = lowestCommonAncestor?.parentIndex ?? destIndex;
+					let attachAncestorIndex = attachPath[sharedDepth]?.parentIndex ?? sourceIndex;
 					if (attachAncestorIndex < sourceIndex) {
 						// The attach path runs through a node located before the detached nodes.
 						// No need to adjust the attach path.
@@ -467,19 +349,14 @@ export class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
 						// 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`.
-						const adjustedAttachAncestorIndex = attachAncestorIndex - count;
-						let parent: NormalizedUpPath =
-							lowestCommonAncestor === undefined
-								? {
-										parent: undefined,
-										detachedNodeId: undefined,
-										parentIndex: adjustedAttachAncestorIndex,
-										parentField: destinationField.field,
-									}
-								: {
-										...lowestCommonAncestor,
-										parentIndex: adjustedAttachAncestorIndex,
-									};
+						attachAncestorIndex -= count;
+						let parent: UpPath | undefined = attachPath[sharedDepth - 1];
+						const parentField = attachPath[sharedDepth] ?? oob();
+						parent = {
+							parent,
+							parentIndex: attachAncestorIndex,
+							parentField: parentField.parentField,
+						};
 						for (let i = sharedDepth + 1; i < attachPath.length; i += 1) {
 							parent = {
 								...(attachPath[i] ?? oob()),
@@ -494,20 +371,19 @@ export class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
 					}
 				}
 			}
-			const moveOut = sequence.changeHandler.editor.remove(
+			const moveOut = sequence.changeHandler.editor.moveOut(
 				sourceIndex,
 				count,
 				detachCellId,
 				revision,
 			);
-			const moveIn = sequence.changeHandler.editor.insert(
+			const moveIn = sequence.changeHandler.editor.moveIn(
 				destIndex,
 				count,
+				detachCellId,
 				attachCellId,
 				revision,
-				detachCellId,
 			);
-
 			this.modularBuilder.submitChanges(
 				[
 					{
@@ -530,113 +406,30 @@ export class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
 		}
 	}
 
-	public sequenceField(
-		field: NormalizedFieldUpPath,
-	): SequenceFieldEditor<TreeChunk, DetachedRootIds> {
-		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 = {
+	public sequenceField(field: FieldUpPath): SequenceFieldEditBuilder<TreeChunk> {
+		return {
 			insert: (index: number, content: TreeChunk): void => {
-				const count = content.topLevelLength;
-				if (count === 0) {
+				const length = content.topLevelLength;
+				if (length === 0) {
 					return;
 				}
+
 				const revision = this.mintRevisionTag();
-				const buildLocalId = this.modularBuilder.generateId();
-				const build = this.modularBuilder.buildTrees(buildLocalId, content, revision);
-				const roots: DetachedRootIdRange = {
-					first: { localId: buildLocalId, revision },
-					count,
+				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 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.enableDetachedRootEditing !== true) {
-					throw new UsageError(
-						`Attach edits require a minimum version for collaboration >= TBD.`,
-					);
-				}
-				if (edits.length > 0) {
-					this.modularBuilder.submitChanges(edits, attachRevision);
-				}
+				// 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);
 			},
 			remove: (index: number, count: number): void => {
 				if (count === 0) {
@@ -650,69 +443,34 @@ export class DefaultIdBasedDataEditor implements IdBasedChangeFamilyDataEditor {
 				this.modularBuilder.submitChange(field, sequence.identifier, change, revision);
 			},
 		};
-		return editBuilder;
 	}
 }
 
-export interface RequiredFieldEditor<TContent, TDetachedRoot> {
+export interface ValueFieldEditBuilder<TContent> {
 	/**
-	 * 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`.
+	 * Issues a change which replaces the current newContent of the field with `newContent`.
 	 * @param newContent - the new content for the field.
 	 */
 	set(newContent: TContent): void;
 }
 
-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;
-
+export interface OptionalFieldEditBuilder<TContent> {
 	/**
-	 * Issues a change which replaces the content of the field with `newContent`
+	 * Issues a change which replaces the current newContent 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;
 }
 
 /**
- * Editor for the sequence field kind.
+ * Edit builder for the sequence field kind.
  */
-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;
-
+export interface SequenceFieldEditBuilder<TContent, TRemoved = 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.
+	 * @param newContent - the new content to be inserted in the field. Cursor can be in either Field or Node mode.
 	 */
 	insert(index: number, newContent: TContent): void;