@fluidframework/tree 2.81.0-374083 → 2.81.1

package/src/feature-libraries/optional-field/optionalField.ts

@@ -7,16 +7,33 @@ import { assert } from "@fluidframework/core-utils/internal";
 
 import {
 	type ChangeAtomId,
+	type ChangeAtomIdMap,
 	type ChangesetLocalId,
-	type DeltaFieldChanges,
+	type DeltaDetachedNodeChanges,
+	type DeltaDetachedNodeId,
 	type DeltaMark,
+	Multiplicity,
 	type RevisionReplacer,
 	type RevisionTag,
-	areEqualChangeAtomIdOpts,
+	areEqualChangeAtomIds,
+	forbiddenFieldKindIdentifier,
 	makeChangeAtomId,
+	taggedAtomId,
 } from "../../core/index.js";
-import type { IdAllocator, Mutable } from "../../util/index.js";
+import {
+	type IdAllocator,
+	type Mutable,
+	SizedNestedMap,
+	deleteFromNestedMap,
+	setInNestedMap,
+	tryGetFromNestedMap,
+} from "../../util/index.js";
 import { nodeIdFromChangeAtom } from "../deltaUtils.js";
+import {
+	optionalIdentifier,
+	identifierFieldIdentifier,
+	requiredIdentifier,
+} from "../fieldKindIdentifiers.js";
 import {
 	type FieldChangeHandler,
 	type FieldChangeRebaser,
@@ -24,159 +41,398 @@ import {
 	type NodeChangeComposer,
 	type NodeChangePruner,
 	type NodeChangeRebaser,
+	NodeAttachState,
 	type NodeId,
+	type RelevantRemovedRootsFromChild,
 	type ToDelta,
 	type NestedChangesIndices,
-	type RebaseNodeManager,
-	type ComposeNodeManager,
-	type InvertNodeManager,
-	type CrossFieldKeyRange,
-	CrossFieldTarget,
-	type RebaseVersion,
-	type RebaseRevisionMetadata,
+	type FieldChangeDelta,
+	FlexFieldKind,
 } from "../modular-schema/index.js";
 
-import type { OptionalChangeset, Replace } from "./optionalFieldChangeTypes.js";
+import type {
+	ChildChange,
+	Move,
+	OptionalChangeset,
+	RegisterId,
+	Replace,
+} from "./optionalFieldChangeTypes.js";
 import { makeOptionalFieldCodecFamily } from "./optionalFieldCodecs.js";
 
-export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
-	compose,
-	invert: (
-		change: OptionalChangeset,
-		isRollback: boolean,
-		genId: IdAllocator<ChangesetLocalId>,
-		revision: RevisionTag | undefined,
-		nodeManager: InvertNodeManager,
-	): OptionalChangeset => {
-		const inverted: Mutable<OptionalChangeset> = {};
-		const detachId = getEffectiveDetachId(change);
-
-		if (detachId !== undefined) {
-			const attachIdForInverse = isRollback
-				? detachId
-				: makeChangeAtomId(detachId.localId, revision);
+export interface IRegisterMap<T> {
+	set(id: RegisterId, childChange: T): void;
+	get(id: RegisterId): T | undefined;
+	delete(id: RegisterId): boolean;
+	keys(): Iterable<RegisterId>;
+	values(): Iterable<T>;
+	entries(): Iterable<[RegisterId, T]>;
+	readonly size: number;
+}
 
-			nodeManager.invertDetach(detachId, 1, change.childChange, attachIdForInverse);
+export class RegisterMap<T> implements IRegisterMap<T> {
+	private readonly nestedMapData = new SizedNestedMap<
+		ChangesetLocalId | "self",
+		RevisionTag | undefined,
+		T
+	>();
+
+	public clone(): RegisterMap<T> {
+		const clone = new RegisterMap<T>();
+		for (const [id, t] of this.entries()) {
+			clone.set(id, t);
+		}
+		return clone;
+	}
 
-			inverted.valueReplace = {
-				isEmpty: change.valueReplace?.src === undefined,
-				dst: makeChangeAtomId(genId.allocate(), revision),
-				src: attachIdForInverse,
-			};
+	public set(id: RegisterId, childChange: T): void {
+		if (id === "self") {
+			this.nestedMapData.set("self", undefined, childChange);
+		} else {
+			this.nestedMapData.set(id.localId, id.revision, childChange);
 		}
+	}
 
-		if (change.valueReplace?.src !== undefined) {
-			const attachEntry = nodeManager.invertAttach(change.valueReplace.src, 1);
-			const detachIdForInverse = invertAttachId(
-				change.valueReplace.src,
-				revision,
-				isRollback,
-				attachEntry.value?.detachId,
-			);
+	public get(id: RegisterId): T | undefined {
+		return id === "self"
+			? this.nestedMapData.tryGet(id, undefined)
+			: this.nestedMapData.tryGet(id.localId, id.revision);
+	}
+
+	public has(id: RegisterId): boolean {
+		return this.get(id) !== undefined;
+	}
+
+	public delete(id: RegisterId): boolean {
+		return id === "self"
+			? this.nestedMapData.delete("self", undefined)
+			: this.nestedMapData.delete(id.localId, id.revision);
+	}
 
-			if (attachEntry.value?.nodeChange !== undefined) {
-				inverted.childChange = attachEntry.value.nodeChange;
+	public keys(): Iterable<RegisterId> {
+		const changeIds: RegisterId[] = [];
+		for (const [localId, nestedMap] of this.nestedMapData) {
+			if (localId === "self") {
+				changeIds.push("self");
+			} else {
+				for (const [revisionTag, _] of nestedMap) {
+					changeIds.push(
+						revisionTag === undefined ? { localId } : { localId, revision: revisionTag },
+					);
+				}
 			}
+		}
 
-			// TODO: Use nodeDetach instead of valueReplace if not supporting older client versions.
-			// inverted.nodeDetach = detachIdForInverse;
-			if (inverted.valueReplace === undefined) {
-				inverted.valueReplace = { isEmpty: false, dst: detachIdForInverse };
+		return changeIds;
+	}
+	public values(): Iterable<T> {
+		return this.nestedMapData.values();
+	}
+	public entries(): Iterable<[RegisterId, T]> {
+		const entries: [RegisterId, T][] = [];
+		for (const changeId of this.keys()) {
+			if (changeId === "self") {
+				const entry = this.nestedMapData.tryGet("self", undefined);
+				assert(
+					entry !== undefined,
+					0x770 /* Entry should not be undefined when iterating keys. */,
+				);
+				entries.push(["self", entry]);
 			} else {
-				(inverted.valueReplace as Mutable<Replace>).dst = detachIdForInverse;
+				const entry = this.nestedMapData.tryGet(changeId.localId, changeId.revision);
+				assert(
+					entry !== undefined,
+					0x771 /* Entry should not be undefined when iterating keys. */,
+				);
+				entries.push([changeId, entry]);
 			}
-		} else if (detachId === undefined && change.childChange !== undefined) {
-			// This change does not affect which node is in the field, so its child change should remain here.
-			inverted.childChange = change.childChange;
 		}
 
-		return inverted;
-	},
+		return entries;
+	}
+	public get size(): number {
+		return this.nestedMapData.size;
+	}
+}
 
-	rebase: (
-		newChange: OptionalChangeset,
-		overChange: OptionalChangeset,
-		rebaseChild: NodeChangeRebaser,
-		_genId: IdAllocator,
-		nodeManager: RebaseNodeManager,
-		_metadata: RebaseRevisionMetadata,
-		rebaseVersion: RebaseVersion,
+export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
+	compose: (
+		change1: OptionalChangeset,
+		change2: OptionalChangeset,
+		composeChild: NodeChangeComposer,
 	): OptionalChangeset => {
-		const rebased: Mutable<OptionalChangeset> = {};
-
-		const rebasedChild = rebaseChild(newChange.childChange, overChange.childChange);
-		const overDetach = getEffectiveDetachId(overChange);
-		if (overDetach !== undefined) {
-			const isPin = areEqualChangeAtomIdOpts(
-				newChange.nodeDetach,
-				newChange.valueReplace?.src,
-			);
+		const { srcToDst, dstToSrc } = getBidirectionalMaps(change1.moves);
+		const change1FieldSrc = change1.valueReplace?.src;
+		const change1FieldDst = getEffectfulDst(change1.valueReplace);
+
+		const change2FieldSrc = change2.valueReplace?.src;
+		let composedFieldSrc: RegisterId | undefined;
+		if (change2FieldSrc !== undefined) {
+			if (change2FieldSrc === "self") {
+				composedFieldSrc = change1FieldSrc ?? change2FieldSrc;
+			} else if (
+				change1FieldDst !== undefined &&
+				areEqualRegisterIds(change1FieldDst, change2FieldSrc)
+			) {
+				composedFieldSrc = "self";
+			} else {
+				composedFieldSrc =
+					tryGetFromNestedMap(dstToSrc, change2FieldSrc.revision, change2FieldSrc.localId) ??
+					change2FieldSrc;
+			}
+		} else if (change1FieldSrc !== undefined && change2.valueReplace === undefined) {
+			composedFieldSrc = change1FieldSrc;
+		}
+
+		const childChanges2ByOriginalId = new RegisterMap<NodeId>();
+		for (const [id, change] of change2.childChanges) {
+			if (id === "self") {
+				if (change1FieldSrc === undefined) {
+					childChanges2ByOriginalId.set("self", change);
+				} else {
+					childChanges2ByOriginalId.set(change1FieldSrc, change);
+				}
+			} else {
+				if (change1FieldDst !== undefined && areEqualChangeAtomIds(change1FieldDst, id)) {
+					childChanges2ByOriginalId.set("self", change);
+				} else {
+					const originalId = tryGetFromNestedMap(dstToSrc, id.revision, id.localId);
+					childChanges2ByOriginalId.set(originalId ?? id, change);
+				}
+			}
+		}
 
-			const nodeDetach = rebaseVersion < 2 && !isPin ? undefined : newChange.nodeDetach;
-			nodeManager.rebaseOverDetach(overDetach, 1, nodeDetach, rebasedChild);
+		const composedMoves: Move[] = [];
+		const composedChildChanges: ChildChange[] = [];
+		const composed: Mutable<OptionalChangeset> = {
+			moves: composedMoves,
+			childChanges: composedChildChanges,
+		};
+
+		for (const [id, childChange1] of change1.childChanges) {
+			const childChange2 = childChanges2ByOriginalId.get(id);
+			composedChildChanges.push([id, composeChild(childChange1, childChange2)]);
+			childChanges2ByOriginalId.delete(id);
 		}
 
-		const overAttach = overChange.valueReplace?.src;
-		if (overAttach !== undefined) {
-			const movedChangeEntry = nodeManager.getNewChangesForBaseAttach(overAttach, 1).value;
+		for (const [id, childChange2] of childChanges2ByOriginalId.entries()) {
+			composedChildChanges.push([id, composeChild(undefined, childChange2)]);
+		}
 
-			if (movedChangeEntry?.nodeChange !== undefined) {
-				rebased.childChange = movedChangeEntry.nodeChange;
+		for (const [leg2Src, leg2Dst] of change2.moves) {
+			const leg1Src = tryGetFromNestedMap(dstToSrc, leg2Src.revision, leg2Src.localId);
+			if (leg1Src !== undefined) {
+				composedMoves.push([leg1Src, leg2Dst]);
+				deleteFromNestedMap(srcToDst, leg1Src.revision, leg1Src.localId);
+				deleteFromNestedMap(dstToSrc, leg2Src.revision, leg2Src.localId);
+			} else if (
+				change1FieldDst === undefined ||
+				!areEqualChangeAtomIds(change1FieldDst, leg2Src)
+			) {
+				composedMoves.push([leg2Src, leg2Dst]);
 			}
+		}
 
-			if (movedChangeEntry?.detachId !== undefined) {
-				rebased.nodeDetach = movedChangeEntry.detachId;
-				if (rebased.valueReplace !== undefined) {
-					// Now that the rebased change has a node detach,
-					// the detach from the value replace no longer takes effect.
-					nodeManager.removeDetach(rebased.valueReplace.dst, 1);
+		for (const [revision, innerMap] of srcToDst.entries()) {
+			for (const [localId, dst] of innerMap.entries()) {
+				const src = makeChangeAtomId(localId, revision);
+				if (composedFieldSrc === undefined || !areEqualRegisterIds(src, composedFieldSrc)) {
+					composedMoves.push([src, dst]);
 				}
 			}
-		} else if (overDetach === undefined) {
-			// `overChange` did not change which node is in the field.
-			if (rebasedChild !== undefined) {
-				rebased.childChange = rebasedChild;
+		}
+
+		if (
+			change1FieldSrc !== undefined &&
+			change1FieldSrc !== "self" &&
+			change2.valueReplace !== undefined
+		) {
+			const change2FieldDst = change2.valueReplace.dst;
+			if (
+				isReplaceEffectful(change2.valueReplace) &&
+				!areEqualChangeAtomIds(change1FieldSrc, change2FieldDst)
+			) {
+				composedMoves.push([change1FieldSrc, change2FieldDst]);
+			}
+		}
+
+		const firstChange = change1.valueReplace ?? change2.valueReplace;
+		if (firstChange === undefined) {
+			return composed;
+		}
+
+		const replace: Mutable<Replace> = {
+			isEmpty: firstChange.isEmpty,
+			dst: getComposedReplaceDst(change1.valueReplace, change2),
+		};
+		if (composedFieldSrc !== undefined) {
+			replace.src = composedFieldSrc;
+		}
+		composed.valueReplace = replace;
+		return composed;
+	},
+
+	invert: (
+		change: OptionalChangeset,
+		isRollback: boolean,
+		genId: IdAllocator<ChangesetLocalId>,
+		revision: RevisionTag | undefined,
+	): OptionalChangeset => {
+		const { moves, childChanges, valueReplace } = change;
+
+		const invertIdMap = new RegisterMap<RegisterId>();
+		const invertedMoves: Move[] = [];
+		for (const [src, dst] of moves) {
+			invertIdMap.set(src, dst);
+			invertedMoves.push([dst, src]);
+		}
+		if (valueReplace !== undefined) {
+			const effectfulDst = getEffectfulDst(valueReplace);
+			if (effectfulDst !== undefined) {
+				invertIdMap.set("self", valueReplace.dst);
+			}
+			if (valueReplace.src !== undefined) {
+				invertIdMap.set(valueReplace.src, "self");
+			}
+		}
+
+		const inverted: Mutable<OptionalChangeset> = {
+			moves: invertedMoves,
+			childChanges: childChanges.map(([id, childChange]) => {
+				return [invertIdMap.get(id) ?? id, childChange];
+			}),
+		};
+
+		if (valueReplace !== undefined) {
+			if (isReplaceEffectful(valueReplace)) {
+				const replace: Mutable<Replace> =
+					valueReplace.src === undefined
+						? {
+								isEmpty: true,
+								dst: makeChangeAtomId(genId.allocate(), revision),
+							}
+						: {
+								isEmpty: false,
+								dst: isRollback
+									? valueReplace.src
+									: makeChangeAtomId(genId.allocate(), revision),
+							};
+				if (valueReplace.isEmpty === false) {
+					replace.src = valueReplace.dst;
+				}
+				inverted.valueReplace = replace;
+			} else if (!isRollback && valueReplace.src === "self") {
+				inverted.valueReplace = {
+					isEmpty: false,
+					src: "self",
+					dst: makeChangeAtomId(genId.allocate(), revision),
+				};
 			}
+		}
+		return inverted;
+	},
 
-			if (newChange.nodeDetach !== undefined) {
-				rebased.nodeDetach = newChange.nodeDetach;
+	rebase: (
+		change: OptionalChangeset,
+		overChange: OptionalChangeset,
+		rebaseChild: NodeChangeRebaser,
+	): OptionalChangeset => {
+		const { moves, childChanges, valueReplace: field } = change;
+
+		// TODO: avoid computing the dstToSrc map if it's not needed.
+		// TODO: de-dupe overSrcToDst and forwardMap
+		const { srcToDst: overSrcToDst } = getBidirectionalMaps(overChange.moves);
+
+		const forwardMap = new RegisterMap<RegisterId>();
+		for (const [src, dst] of overChange.moves) {
+			forwardMap.set(src, dst);
+		}
+		if (overChange.valueReplace !== undefined) {
+			const effectfulDst = getEffectfulDst(overChange.valueReplace);
+			if (effectfulDst !== undefined) {
+				forwardMap.set("self", overChange.valueReplace.dst);
+			}
+			if (overChange.valueReplace.src !== undefined) {
+				forwardMap.set(overChange.valueReplace.src, "self");
 			}
 		}
 
-		if (newChange.valueReplace !== undefined) {
-			const isEmpty =
-				overDetach !== undefined || overChange.valueReplace !== undefined
-					? overChange.valueReplace?.src === undefined
-					: newChange.valueReplace.isEmpty;
+		const rebasedMoves: Move[] = [];
+		for (const [src, dst] of moves) {
+			const newDst = tryGetFromNestedMap(overSrcToDst, src.revision, src.localId);
+			rebasedMoves.push([src, newDst ?? dst]);
+		}
 
-			rebased.valueReplace = { ...newChange.valueReplace, isEmpty };
+		const overChildChangesBySrc = new RegisterMap<NodeId>();
+		for (const [id, childChange] of overChange.childChanges) {
+			overChildChangesBySrc.set(id, childChange);
 		}
 
-		const detachId = getEffectiveDetachId(newChange);
-		const rebasedDetachId = getEffectiveDetachId(rebased);
+		const rebasedChildChanges: ChildChange[] = [];
+		for (const [id, childChange] of childChanges) {
+			const overChildChange = overChildChangesBySrc.get(id);
+			if (overChildChange !== undefined) {
+				overChildChangesBySrc.delete(id);
+			}
 
-		if (detachId !== undefined && !areEqualChangeAtomIdOpts(detachId, rebasedDetachId)) {
-			nodeManager.removeDetach(detachId, 1);
+			const rebasedId = forwardMap.get(id) ?? id;
+			const rebasedChildChange = rebaseChild(
+				childChange,
+				overChildChange,
+				rebasedId === "self" ? NodeAttachState.Attached : NodeAttachState.Detached,
+			);
+			if (rebasedChildChange !== undefined) {
+				rebasedChildChanges.push([rebasedId, rebasedChildChange]);
+			}
 		}
 
-		if (
-			rebasedDetachId !== undefined &&
-			!areEqualChangeAtomIdOpts(rebasedDetachId, detachId)
-		) {
-			nodeManager.addDetach(rebasedDetachId, 1);
+		for (const [id, overChildChange] of overChildChangesBySrc.entries()) {
+			const rebasedId = forwardMap.get(id) ?? id;
+			const rebasedChildChange = rebaseChild(
+				undefined,
+				overChildChange,
+				rebasedId === "self" ? NodeAttachState.Attached : NodeAttachState.Detached,
+			);
+			if (rebasedChildChange !== undefined) {
+				rebasedChildChanges.push([rebasedId, rebasedChildChange]);
+			}
+		}
+
+		const rebased: Mutable<OptionalChangeset> = {
+			moves: rebasedMoves,
+			childChanges: rebasedChildChanges,
+		};
+
+		if (field !== undefined) {
+			const replace: Mutable<Replace> = {
+				isEmpty:
+					overChange.valueReplace === undefined
+						? field.isEmpty
+						: overChange.valueReplace.src === undefined,
+				dst: field.dst,
+			};
+			if (field.src !== undefined) {
+				replace.src = forwardMap.get(field.src) ?? field.src;
+			}
+			rebased.valueReplace = replace;
 		}
 
 		return rebased;
 	},
 
 	prune: (change: OptionalChangeset, pruneChild: NodeChangePruner): OptionalChangeset => {
-		const prunedChange: Mutable<OptionalChangeset> = { ...change };
+		const childChanges: ChildChange[] = [];
+		const prunedChange: Mutable<OptionalChangeset> = {
+			moves: change.moves,
+			childChanges,
+		};
+		if (change.valueReplace !== undefined) {
+			prunedChange.valueReplace = change.valueReplace;
+		}
 
-		delete prunedChange.childChange;
-		if (change.childChange !== undefined) {
-			const childChange = pruneChild(change.childChange);
-			if (childChange !== undefined) {
-				prunedChange.childChange = childChange;
+		for (const [id, childChange] of change.childChanges) {
+			const prunedChildChange = pruneChild(childChange);
+			if (prunedChildChange !== undefined) {
+				childChanges.push([id, prunedChildChange]);
 			}
 		}
 
@@ -187,14 +443,22 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 		change: OptionalChangeset,
 		replacer: RevisionReplacer,
 	): OptionalChangeset => {
-		const updated: Mutable<OptionalChangeset> = {};
-
 		const valueReplace = replaceReplaceRevisions(change.valueReplace, replacer);
 
-		if (change.childChange !== undefined) {
-			updated.childChange = replacer.getUpdatedAtomId(change.childChange);
+		const childChanges: ChildChange[] = [];
+		for (const [id, childChange] of change.childChanges) {
+			childChanges.push([
+				replaceRegisterRevisions(id, replacer),
+				replacer.getUpdatedAtomId(childChange),
+			]);
+		}
+
+		const moves: Move[] = [];
+		for (const [src, dst] of change.moves) {
+			moves.push([replacer.getUpdatedAtomId(src), replacer.getUpdatedAtomId(dst)]);
 		}
 
+		const updated: Mutable<OptionalChangeset> = { childChanges, moves };
 		if (valueReplace !== undefined) {
 			updated.valueReplace = valueReplace;
 		}
@@ -203,189 +467,130 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 	},
 
 	mute: (change: OptionalChangeset): OptionalChangeset => {
-		return { childChange: change.childChange };
+		return { childChanges: change.childChanges, moves: [] };
 	},
 };
 
-function compose(
-	change1: OptionalChangeset,
-	change2: OptionalChangeset,
-	composeChild: NodeChangeComposer,
-	_genId: IdAllocator,
-	nodeManager: ComposeNodeManager,
-): OptionalChangeset {
-	const detachId2 = getEffectiveDetachId(change2);
-	if (change1.valueReplace?.src !== undefined && detachId2 !== undefined) {
-		nodeManager.composeAttachDetach(change1.valueReplace.src, detachId2, 1);
+function replaceReplaceRevisions(
+	replace: Replace | undefined,
+	replacer: RevisionReplacer,
+): Replace | undefined {
+	if (replace === undefined) {
+		return undefined;
 	}
 
-	const composedDetach = composeNodeDetaches(change1, change2, nodeManager);
-	const composedReplace = composeReplaces(change1, change2);
-	const composedChildChange = getComposedChildChanges(
-		change1,
-		change2,
-		nodeManager,
-		composeChild,
-	);
-
-	sendNewChildChanges(change1, change2, nodeManager);
+	const updated: Mutable<Replace> = {
+		...replace,
+		dst: replacer.getUpdatedAtomId(replace.dst),
+	};
 
-	if (
-		change1.nodeDetach !== undefined &&
-		areEqualChangeAtomIdOpts(change1.nodeDetach, change2.valueReplace?.src)
-	) {
-		nodeManager.composeDetachAttach(change1.nodeDetach, change1.nodeDetach, 1, true);
+	if (replace.src !== undefined) {
+		updated.src = replaceRegisterRevisions(replace.src, replacer);
 	}
 
-	return makeChangeset(composedReplace, composedDetach, composedChildChange);
+	return updated;
 }
 
-function composeNodeDetaches(
-	change1: OptionalChangeset,
-	change2: OptionalChangeset,
-	nodeManager: ComposeNodeManager,
-): ChangeAtomId | undefined {
-	const detach1 = getEffectiveDetachId(change1);
-	if (detach1 !== undefined) {
-		const newDetachId = nodeManager.getNewChangesForBaseDetach(detach1, 1).value?.detachId;
-		if (newDetachId !== undefined) {
-			return newDetachId;
-		}
-	}
-
-	if (change1.nodeDetach !== undefined) {
-		return change1.nodeDetach;
-	}
-
-	return detach1 !== undefined || change1.valueReplace?.isEmpty === true
-		? undefined
-		: change2.nodeDetach;
+function replaceRegisterRevisions(
+	register: RegisterId,
+	replacer: RevisionReplacer,
+): RegisterId {
+	return register === "self" ? register : replacer.getUpdatedAtomId(register);
 }
 
-function composeReplaces(
-	change1: OptionalChangeset,
+function getComposedReplaceDst(
+	change1: Replace | undefined,
 	change2: OptionalChangeset,
-): Replace | undefined {
-	const firstReplace = change1.valueReplace ?? change2.valueReplace;
-	if (firstReplace === undefined) {
-		return undefined;
+): ChangeAtomId {
+	const dst1 = change1?.dst;
+	if (change2.valueReplace === undefined) {
+		assert(dst1 !== undefined, 0x8ce /* Both replace replaces should not be undefined */);
+		return getIdAfterMoves(dst1, change2.moves);
 	}
 
-	const isEmpty = change1.nodeDetach === undefined ? firstReplace.isEmpty : false;
-	const replace: Mutable<Replace> = { isEmpty, dst: firstReplace.dst };
-	if (change2.valueReplace?.src !== undefined) {
-		replace.src = change2.valueReplace.src;
-	} else if (
-		getEffectiveDetachId(change2) === undefined &&
-		change1.valueReplace?.src !== undefined
+	if (
+		dst1 === undefined ||
+		change1?.src === "self" ||
+		(change2.valueReplace.src !== undefined &&
+			areEqualRegisterIds(change2.valueReplace.src, dst1))
 	) {
-		replace.src = change1.valueReplace.src;
-	}
-
-	return replace;
-}
-
-/**
- * Informs the node manager of any child changes in `change2` that may need to be represented somewhere else in the input context of the composed changeset.
- * See {@link ComposeNodeManager.sendNewChangesToBaseSourceLocation} for motivation.
- * @param change1 - The first change to compose. Conceptually applies before `change2`.
- * @param change2 - The second change to compose. Conceptually applies after `change1`.
- * @param nodeManager - The node manager that needs to be informed of the child changes.
- */
-function sendNewChildChanges(
-	change1: OptionalChangeset,
-	change2: OptionalChangeset,
-	nodeManager: ComposeNodeManager,
-): void {
-	if (change2.childChange !== undefined && change1.valueReplace?.src !== undefined) {
-		// The presence of new child implies that there is some node present in the field in the input context of change2.
-		// The fact that the change1 has a shallow effect implies that this node was attached by change1.
-		nodeManager.sendNewChangesToBaseSourceLocation(
-			change1.valueReplace.src,
-			change2.childChange,
+		assert(
+			change2.valueReplace !== undefined,
+			0x8cf /* Both replace replaces should not be undefined */,
 		);
+		return change2.valueReplace.dst;
+	} else {
+		return getIdAfterMoves(dst1, change2.moves);
 	}
 }
 
-/**
- * Computes the child changes that should be included in the composed changeset.
- * @param change1 - The first change to compose. Conceptually applies before `change2`.
- * @param change2 - The second change to compose. Conceptually applies after `change1`.
- * @param nodeManager - The node manager. Provides information about potential child changes from `change2`.
- * @param composeChild - The delegate to compose child changes.
- * @returns The composed child changes (if any) for the node (if any) present in the field in the input context of `change1`.
- */
-function getComposedChildChanges(
-	change1: OptionalChangeset,
-	change2: OptionalChangeset,
-	nodeManager: ComposeNodeManager,
-	composeChild: NodeChangeComposer,
-): NodeId | undefined {
-	const detachId1 = getEffectiveDetachId(change1);
-
-	// We need to determine what the child changes are in change2 for the node (if any) that resides in the field in the input context of change1.
-	const childChangesFromChange2: NodeId | undefined =
-		// If such a node did exist, the changes for it in change2 would come from wherever change1 sends that node.
-		// Note: in both branches of this ternary, we are leveraging the fact querying for changes of a non-existent node safely yields undefined
-		detachId1 === undefined
-			? change1.valueReplace?.src === undefined
-				? change2.childChange
-				: undefined
-			: nodeManager.getNewChangesForBaseDetach(detachId1, 1).value?.nodeChange;
-
-	let composedChildChange: NodeId | undefined;
-	if (change1.childChange !== undefined || childChangesFromChange2 !== undefined) {
-		composedChildChange = composeChild(change1.childChange, childChangesFromChange2);
+function getIdAfterMoves(id: ChangeAtomId, moves: readonly Move[]): ChangeAtomId {
+	for (const [src, dst] of moves) {
+		if (areEqualChangeAtomIds(id, src)) {
+			return dst;
+		}
 	}
-	return composedChildChange;
+	return id;
 }
 
-function makeChangeset(
-	replace: Replace | undefined,
-	detachId: ChangeAtomId | undefined,
-	childChange: NodeId | undefined,
-): OptionalChangeset {
-	const changeset: Mutable<OptionalChangeset> = {};
-	if (replace !== undefined) {
-		changeset.valueReplace = replace;
-	}
-
-	if (detachId !== undefined) {
-		changeset.nodeDetach = detachId;
-	}
+function areEqualRegisterIds(id1: RegisterId, id2: RegisterId): boolean {
+	return id1 === "self" || id2 === "self" ? id1 === id2 : areEqualChangeAtomIds(id1, id2);
+}
 
-	if (childChange !== undefined) {
-		changeset.childChange = childChange;
+function areEqualRegisterIdsOpt(
+	id1: RegisterId | undefined,
+	id2: RegisterId | undefined,
+): boolean {
+	if (id1 === undefined || id2 === undefined) {
+		return id1 === id2;
 	}
-	return changeset;
+	return areEqualRegisterIds(id1, id2);
 }
 
-function replaceReplaceRevisions(
-	replace: Replace | undefined,
-	replacer: RevisionReplacer,
-): Replace | undefined {
-	if (replace === undefined) {
-		return undefined;
+function getBidirectionalMaps(moves: OptionalChangeset["moves"]): {
+	srcToDst: ChangeAtomIdMap<ChangeAtomId>;
+	dstToSrc: ChangeAtomIdMap<ChangeAtomId>;
+} {
+	const srcToDst: ChangeAtomIdMap<ChangeAtomId> = new Map();
+	const dstToSrc: ChangeAtomIdMap<ChangeAtomId> = new Map();
+	for (const [src, dst] of moves) {
+		setInNestedMap(srcToDst, src.revision, src.localId, dst);
+		setInNestedMap(dstToSrc, dst.revision, dst.localId, src);
 	}
+	return { srcToDst, dstToSrc };
+}
 
-	const updated: Mutable<Replace> = {
-		...replace,
-		dst: replacer.getUpdatedAtomId(replace.dst),
-	};
-
-	if (replace.src !== undefined) {
-		updated.src = replacer.getUpdatedAtomId(replace.src);
+type EffectfulReplace =
+	| {
+			isEmpty: true;
+			src?: ChangeAtomId;
+			dst: ChangeAtomId;
+	  }
+	| {
+			isEmpty: boolean;
+			src: ChangeAtomId;
+			dst: ChangeAtomId;
+	  };
+
+function isReplaceEffectful(replace: Replace): replace is EffectfulReplace {
+	if (replace.src === "self") {
+		return false;
 	}
+	return !replace.isEmpty || replace.src !== undefined;
+}
 
-	return updated;
+function getEffectfulDst(replace: Replace | undefined): ChangeAtomId | undefined {
+	return replace === undefined || replace.isEmpty || replace.src === "self"
+		? undefined
+		: replace.dst;
 }
 
-function getEffectiveDetachId(change: OptionalChangeset): ChangeAtomId | undefined {
-	if (change.nodeDetach !== undefined) {
-		return change.nodeDetach;
+export function taggedRegister(id: RegisterId, revision: RevisionTag | undefined): RegisterId {
+	if (id === "self") {
+		return id;
 	}
 
-	return change.valueReplace?.isEmpty === false ? change.valueReplace.dst : undefined;
+	return taggedAtomId(id, revision);
 }
 
 export interface OptionalFieldEditor extends FieldEditor<OptionalChangeset> {
@@ -402,7 +607,6 @@ export interface OptionalFieldEditor extends FieldEditor<OptionalChangeset> {
 		ids: {
 			fill: ChangeAtomId;
 			detach: ChangeAtomId;
-			detachNode?: ChangeAtomId;
 		},
 	): OptionalChangeset;
 
@@ -421,18 +625,20 @@ export const optionalFieldEditor: OptionalFieldEditor = {
 			fill: ChangeAtomId;
 			// Should be interpreted as a set of an empty field if undefined.
 			detach: ChangeAtomId;
-			detachNode?: ChangeAtomId;
 		},
 	): OptionalChangeset => ({
+		moves: [],
+		childChanges: [],
 		valueReplace: {
 			isEmpty: wasEmpty,
 			src: ids.fill,
 			dst: ids.detach,
 		},
-		nodeDetach: ids.detachNode,
 	}),
 
 	clear: (wasEmpty: boolean, detachId: ChangeAtomId): OptionalChangeset => ({
+		moves: [],
+		childChanges: [],
 		valueReplace: {
 			isEmpty: wasEmpty,
 			dst: detachId,
@@ -440,44 +646,74 @@ export const optionalFieldEditor: OptionalFieldEditor = {
 	}),
 
 	buildChildChanges: (changes: Iterable<[number, NodeId]>): OptionalChangeset => {
-		const childChanges: NodeId[] = Array.from(changes, ([index, child]) => {
+		const childChanges: ChildChange[] = Array.from(changes, ([index, childChange]) => {
 			assert(index === 0, 0x404 /* Optional fields only support a single child node */);
-			return child;
+			return ["self", childChange];
 		});
 		assert(
 			childChanges.length <= 1,
 			0xabd /* Optional fields only support a single child node */,
 		);
-
-		const childChange = childChanges[0];
-		return childChange === undefined ? {} : { childChange };
+		return {
+			moves: [],
+			childChanges,
+		};
 	},
 };
 
 export function optionalFieldIntoDelta(
 	change: OptionalChangeset,
 	deltaFromChild: ToDelta,
-): DeltaFieldChanges {
+): FieldChangeDelta {
+	const delta: Mutable<FieldChangeDelta> = {};
+
 	let markIsANoop = true;
 	const mark: Mutable<DeltaMark> = { count: 1 };
-	const detachId = getEffectiveDetachId(change);
-	const attachId = change.valueReplace?.src;
-	if (detachId !== undefined && !areEqualChangeAtomIdOpts(detachId, attachId)) {
-		mark.detach = nodeIdFromChangeAtom(detachId);
+
+	if (change.valueReplace !== undefined && isReplaceEffectful(change.valueReplace)) {
+		if (!change.valueReplace.isEmpty) {
+			mark.detach = nodeIdFromChangeAtom(change.valueReplace.dst);
+		}
+		if (change.valueReplace.src !== undefined) {
+			mark.attach = nodeIdFromChangeAtom(change.valueReplace.src);
+		}
 		markIsANoop = false;
 	}
 
-	if (attachId !== undefined && !areEqualChangeAtomIdOpts(attachId, detachId)) {
-		mark.attach = nodeIdFromChangeAtom(attachId);
-		markIsANoop = false;
+	if (change.moves.length > 0) {
+		delta.rename = change.moves.map(([src, dst]) => ({
+			count: 1,
+			oldId: nodeIdFromChangeAtom(src),
+			newId: nodeIdFromChangeAtom(dst),
+		}));
 	}
 
-	if (change.childChange !== undefined) {
-		mark.fields = deltaFromChild(change.childChange);
-		markIsANoop = false;
+	if (change.childChanges.length > 0) {
+		const globals: DeltaDetachedNodeChanges[] = [];
+		for (const [id, childChange] of change.childChanges) {
+			const childDelta = deltaFromChild(childChange);
+			if (id === "self") {
+				mark.fields = childDelta;
+				markIsANoop = false;
+			} else {
+				const fields = childDelta;
+				globals.push({
+					id: { major: id.revision, minor: id.localId },
+					fields,
+				});
+			}
+		}
+
+		if (globals.length > 0) {
+			delta.global = globals;
+		}
 	}
 
-	return markIsANoop ? [] : [mark];
+	if (!markIsANoop) {
+		delta.local = [mark];
+	}
+
+	return delta;
 }
 
 export const optionalChangeHandler: FieldChangeHandler<
@@ -489,53 +725,92 @@ export const optionalChangeHandler: FieldChangeHandler<
 	editor: optionalFieldEditor,
 
 	intoDelta: optionalFieldIntoDelta,
+	relevantRemovedRoots,
 
 	isEmpty: (change: OptionalChangeset) =>
-		change.childChange === undefined &&
-		change.valueReplace === undefined &&
-		change.nodeDetach === undefined,
+		change.childChanges.length === 0 &&
+		change.moves.length === 0 &&
+		change.valueReplace === undefined,
 
 	getNestedChanges,
 
-	createEmpty: () => ({}),
-	getCrossFieldKeys,
+	createEmpty: () => ({ moves: [], childChanges: [] }),
+	getCrossFieldKeys: (_change) => [],
 };
 
-function getCrossFieldKeys(change: OptionalChangeset): CrossFieldKeyRange[] {
-	const keys: CrossFieldKeyRange[] = [];
-	if (change.valueReplace?.src !== undefined) {
-		keys.push({
-			key: { ...change.valueReplace.src, target: CrossFieldTarget.Destination },
-			count: 1,
-		});
-	}
-
-	const detachId = getEffectiveDetachId(change);
+function getNestedChanges(change: OptionalChangeset): NestedChangesIndices {
+	// True iff the content of the field changes in some way
+	const isFieldContentChanged =
+		change.valueReplace !== undefined && change.valueReplace.src !== "self";
+
+	// The node that is moved into the field (if any).
+	const nodeMovedIntoField = change.valueReplace?.src;
+
+	return change.childChanges.map(([register, nodeId]) => {
+		// The node is removed in the input context iif register is not self.
+		const inputIndex = register === "self" ? 0 : undefined;
+		const outputIndex =
+			register === "self"
+				? // If the node starts out as not-removed, it is removed in the output context iff the field content is changed
+					isFieldContentChanged
+					? undefined
+					: 0
+				: // If the node starts out as removed, then it remains removed in the output context iff it is not the node that is moved into the field
+					areEqualRegisterIdsOpt(register, nodeMovedIntoField)
+					? 0
+					: undefined;
+		return [nodeId, inputIndex, outputIndex];
+	});
+}
 
-	if (detachId !== undefined) {
-		keys.push({ key: { ...detachId, target: CrossFieldTarget.Source }, count: 1 });
+function* relevantRemovedRoots(
+	change: OptionalChangeset,
+	relevantRemovedRootsFromChild: RelevantRemovedRootsFromChild,
+): Iterable<DeltaDetachedNodeId> {
+	const alreadyYielded = new RegisterMap<boolean>();
+
+	for (const [src] of change.moves) {
+		if (!alreadyYielded.has(src)) {
+			alreadyYielded.set(src, true);
+			yield nodeIdFromChangeAtom(src);
+		}
 	}
 
-	return keys;
-}
-
-function getNestedChanges(change: OptionalChangeset): NestedChangesIndices {
-	if (change.childChange === undefined) {
-		return [];
+	for (const [id, childChange] of change.childChanges) {
+		// Child changes make the tree they apply to relevant unless that tree existed in the starting context of
+		// of this change.
+		if (id !== "self" && !alreadyYielded.has(id)) {
+			alreadyYielded.set(id, true);
+			yield nodeIdFromChangeAtom(id);
+		}
+		yield* relevantRemovedRootsFromChild(childChange);
 	}
 
-	return [[change.childChange, 0]];
+	const selfSrc = change.valueReplace?.src;
+	if (selfSrc !== undefined && selfSrc !== "self" && !alreadyYielded.has(selfSrc)) {
+		yield nodeIdFromChangeAtom(selfSrc);
+	}
 }
 
-function invertAttachId(
-	attachId: ChangeAtomId,
-	revision: RevisionTag | undefined,
-	isRollback: boolean,
-	detachId: ChangeAtomId | undefined,
-): ChangeAtomId {
-	if (!isRollback) {
-		return makeChangeAtomId(attachId.localId, revision);
-	}
+interface Optional
+	extends FlexFieldKind<
+		OptionalFieldEditor,
+		typeof optionalIdentifier,
+		Multiplicity.Optional
+	> {}
 
-	return detachId ?? attachId;
-}
+/**
+ * 0 or 1 items.
+ */
+export const optional: Optional = new FlexFieldKind(
+	optionalIdentifier,
+	Multiplicity.Optional,
+	{
+		changeHandler: optionalChangeHandler,
+		allowMonotonicUpgradeFrom: new Set([
+			identifierFieldIdentifier,
+			requiredIdentifier,
+			forbiddenFieldKindIdentifier,
+		]),
+	},
+);