Improve applySerializedChange to support cross-session usage and transactions

packages/dds/tree/src/core/rebase/types.ts

@@ -210,7 +210,6 @@ export interface LocalChangeMetadata extends CommitMetadata {
 	 * Returns a serializable object that encodes the change.
 	 * @remarks This is only available for local changes.
 	 * This change object can be {@link TreeBranchAlpha.applyChange | applied to another branch} in the same state as the one which generated it.
-	 * The change object must be applied to a SharedTree with the same IdCompressor session ID as it was created from.
 	 * @privateRemarks
 	 * This is a `SerializedChange` from treeCheckout.ts.
 	 */

packages/dds/tree/src/feature-libraries/default-schema/defaultEditBuilder.ts

@@ -204,6 +204,7 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 			fieldKinds,
 			changeReceiver,
 			codecOptions,
+			mintRevisionTag,
 		);
 	}
 
@@ -214,6 +215,10 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		this.modularBuilder.exitTransaction();
 	}
 
+	public applyExternalChange(change: DefaultChangeset): void {
+		this.modularBuilder.applyExternalChange(change);
+	}
+
 	public addNodeExistsConstraint(path: UpPath): void {
 		this.modularBuilder.addNodeExistsConstraint(path, this.mintRevisionTag());
 	}

packages/dds/tree/src/feature-libraries/modular-schema/defaultRevisionReplacer.ts

@@ -18,6 +18,7 @@ import {
 	brand,
 	brandConst,
 	newIntegerRangeMap,
+	type IdAllocator,
 	type RangeMap,
 	type Mutable,
 } from "../../util/index.js";
@@ -40,10 +41,25 @@ export class DefaultRevisionReplacer implements RevisionReplacer {
 	 */
 	private maxSeen: ChangesetLocalId = brandConst(-1)();
 
+	/**
+	 * @param updatedRevision - The revision to assign to all replaced IDs.
+	 * @param obsoleteRevisions - The set of revisions that should be replaced.
+	 * @param idAllocator - If provided, IDs already allocated by this allocator will be reserved (avoided by the replacer),
+	 * and the allocator will be updated to account for any new IDs allocated during replacement.
+	 */
 	public constructor(
 		public readonly updatedRevision: RevisionTag,
 		private readonly obsoleteRevisions: Set<RevisionTag | undefined>,
-	) {}
+		private readonly idAllocator?: IdAllocator,
+	) {
+		if (idAllocator !== undefined) {
+			const reservedIdCount = idAllocator.getMaxId() + 1;
+			if (reservedIdCount > 0) {
+				this.localIds.set(brand(0), reservedIdCount, true);
+				this.maxSeen = brand(reservedIdCount - 1);
+			}
+		}
+	}
 
 	public isObsolete(revision: RevisionTag | undefined): boolean {
 		return this.obsoleteRevisions.has(revision);
@@ -89,6 +105,12 @@ export class DefaultRevisionReplacer implements RevisionReplacer {
 				remainderStart = offsetChangeAtomId(remainderStart, prior.length);
 				remainderCount -= prior.length;
 			}
+
+			// Keep the allocator in sync with any new IDs we've allocated
+			if (this.idAllocator !== undefined && this.maxSeen >= this.idAllocator.getMaxId() + 1) {
+				this.idAllocator.allocate(this.maxSeen - this.idAllocator.getMaxId());
+			}
+
 			return updated;
 		}
 		return id;

packages/dds/tree/src/feature-libraries/modular-schema/modularChangeFamily.ts

@@ -81,6 +81,7 @@ import {
 	getFirstFromCrossFieldMap,
 	setInCrossFieldMap,
 } from "./crossFieldQueries.js";
+import { DefaultRevisionReplacer } from "./defaultRevisionReplacer.js";
 import {
 	type FieldChangeHandler,
 	NodeAttachState,
@@ -2686,6 +2687,7 @@ export class ModularEditBuilder extends EditBuilder<ModularChangeset> {
 		private readonly fieldKinds: ReadonlyMap<FieldKindIdentifier, FlexFieldKind>,
 		changeReceiver: (change: TaggedChange<ModularChangeset>) => void,
 		codecOptions: CodecWriteOptions,
+		private readonly mintRevisionTag?: () => RevisionTag,
 	) {
 		super(family, changeReceiver);
 		this.idAllocator = idAllocatorFromMaxId();
@@ -2707,6 +2709,27 @@ export class ModularEditBuilder extends EditBuilder<ModularChangeset> {
 		}
 	}
 
+	/**
+	 * Apply a changeset that originated from a different editor.
+	 * @remarks
+	 * The revision for the change will be changed to a new revision (using `mintRevisionTag`) before application.
+	 * The change will also have its local IDs replaced to avoid collisions with any IDs produced by this editor.
+	 */
+	public applyExternalChange(change: ModularChangeset): void {
+		assert(
+			this.mintRevisionTag !== undefined,
+			"mintRevisionTag is required to apply external changes",
+		);
+		const revision = this.mintRevisionTag();
+		const replacer = new DefaultRevisionReplacer(
+			revision,
+			this.changeFamily.rebaser.getRevisions(change),
+			this.idAllocator,
+		);
+		const newChange = this.changeFamily.rebaser.changeRevision(change, replacer);
+		this.applyChange(tagChange(newChange, revision));
+	}
+
 	/**
 	 * Builds a new tree to use in an edit.
 	 *

packages/dds/tree/src/shared-tree/treeCheckout.ts

@@ -715,6 +715,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 							idCompressor: this.idCompressor,
 							originatorId: this.idCompressor.localSessionId,
 							revision,
+							schema: undefined, // By not passing the schema, we avoid compressing identifiers in identifier fields
 						};
 						const encodedChange = this.changeFamily.codecs.resolve(4).encode(change, context);
 
@@ -775,19 +776,24 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			throw new UsageError(`Cannot apply change. Invalid serialized change format.`);
 		}
 		const { revision, originatorId, change } = serializedChange;
-		if (originatorId !== this.idCompressor.localSessionId) {
-			throw new UsageError(
-				`Cannot apply change. A serialized changed must be applied to the same SharedTree as it was created from.`,
-			);
-		}
 		const context: ChangeEncodingContext = {
 			idCompressor: this.idCompressor,
-			originatorId: this.idCompressor.localSessionId,
+			originatorId,
 			revision,
 		};
 		const decodedChange = this.changeFamily.codecs.resolve(4).decode(change, context);
-		// Apply the change to the branch, but _not_ the `activeBranch` - we do not support squashing serialized commits in a transaction.
-		this.#transaction.branch.apply(tagChange(decodedChange, revision));
+
+		// Extract the inner data change from the SharedTreeChange envelope.
+		// Serialized changes are always single data changes (not schema changes).
+		const innerChange = decodedChange.changes[0];
+		assert(
+			decodedChange.changes.length === 1 && innerChange?.type === "data",
+			0x1b2 /* Expected a single data change in serialized change */,
+		);
+
+		// Delegate to the editor, which will replace the revision, shift local IDs to avoid
+		// collisions with other changes in the same transaction, and apply the change.
+		this.#transaction.activeBranchEditor.applyExternalChange(innerChange.innerChange);
 	}
 
 	// Revision is the revision of the commit, if any, which caused this change.

packages/dds/tree/src/simple-tree/api/tree.ts

@@ -332,12 +332,11 @@ export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
 	 * Apply a serialized change to this branch.
 	 * @param change - the change to apply.
 	 * Changes are acquired via `getChange` in a branch's {@link TreeBranchEvents.changed | "changed"} event.
-	 * @remarks Changes may only be applied to a SharedTree with the same IdCompressor instance and branch state from which they were generated.
-	 * They may be created by one branch and applied to another, but only if both branches share the same history at the time of creation and application.
+	 * @remarks Changes may only be applied to a SharedTree with the same branch state from which they were generated.
+	 * They may be created by one branch and applied to another, but only if both branches share the same history at the time of creation and application, respectively.
+	 * The two branches may use different IdCompressor instances (e.g. across different runtimes or processes).
 	 *
-	 * @privateRemarks
-	 * TODO: This method will support applying changes from different IdCompressor instances as long as they have the same local session ID.
-	 * Update the tests and docs to match when that is done.
+	 * Applying changes is not idempotent, that is, the same serialized change applied twice will have two effects - it will not be deduplicated.
 	 */
 	applyChange(change: JsonCompatibleReadOnly): void;
 }