@fluidframework/tree 2.113.1 → 2.115.0

package/src/shared-tree/sharedTree.ts

@@ -52,6 +52,7 @@ import {
 	TreeCompressionStrategy,
 	buildChunkedForest,
 	buildForest,
+	ComparisonForest,
 	defaultIncrementalEncodingPolicy,
 	defaultSchemaPolicy,
 	fieldBatchCodecBuilder,
@@ -105,6 +106,7 @@ import {
 	getCodecTreeForChangeFormat,
 	SharedTreeChangeFormatVersion,
 } from "./sharedTreeChangeCodecs.js";
+import type { SharedTreeChangeProcessingContext } from "./sharedTreeChangeFamily.js";
 import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
@@ -174,7 +176,11 @@ export type SharedTreeKernelView = Omit<ITreePrivate, keyof (IChannelView & IFlu
  */
 @breakingClass
 export class SharedTreeKernel
-	extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>
+	extends SharedTreeCore<
+		SharedTreeEditBuilder,
+		SharedTreeChange,
+		SharedTreeChangeProcessingContext
+	>
 	implements SharedKernel
 {
 	public readonly checkout: TreeCheckout;
@@ -219,13 +225,7 @@ export class SharedTreeKernel
 			idCompressor,
 			options.shouldEncodeIncrementally,
 		);
-		const revisionTagCodec = new RevisionTagCodec(idCompressor);
-		const removedRoots = makeDetachedFieldIndex(
-			"repair",
-			revisionTagCodec,
-			idCompressor,
-			options,
-		);
+		const removedRoots = makeDetachedFieldIndex("repair");
 		const schemaCodec = schemaCodecBuilder.build(options);
 		const schemaSummarizer = new SchemaSummarizer(
 			schema,
@@ -252,12 +252,11 @@ export class SharedTreeKernel
 			idCompressor,
 			healing:
 				options.healUnresolvableIdentifiersOnDecode === true
-					? { sharedObjectId: sharedObject.id }
+					? { sharedObjectId: sharedObject.id, logger }
 					: undefined,
 		});
 		const forestSummarizer = new ForestSummarizer(
 			forest,
-			revisionTagCodec,
 			encoderContext,
 			decoderContext,
 			options,
@@ -265,9 +264,12 @@ export class SharedTreeKernel
 			initialSequenceNumber,
 			options.shouldEncodeIncrementally,
 		);
+		const revisionTagCodec = new RevisionTagCodec(idCompressor);
 		const removedRootsSummarizer = new DetachedFieldIndexSummarizer(
 			removedRoots,
-			options.minVersionForCollab,
+			revisionTagCodec,
+			idCompressor,
+			options,
 		);
 		const innerChangeFamily = new SharedTreeChangeFamily(
 			revisionTagCodec,
@@ -436,7 +438,11 @@ export class SharedTreeKernel
 
 	public override applyStashedOp(
 		...args: Parameters<
-			SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>["applyStashedOp"]
+			SharedTreeCore<
+				SharedTreeEditBuilder,
+				SharedTreeChange,
+				SharedTreeChangeProcessingContext
+			>["applyStashedOp"]
 		>
 	): void {
 		for (const checkout of this.checkouts.values()) {
@@ -596,6 +602,11 @@ export interface SharedTreeOptionsBeta extends ForestOptions, Partial<CodecWrite
 	 * Healed identifiers are written back out at the next summary in their stable UUID form,
 	 * so the inconsistency does not need to be re-healed on every load.
 	 *
+	 * When this flag is enabled, each time an unresolvable identifier is healed a
+	 * `HealUnresolvableIdentifierOnDecode` telemetry event is emitted (at
+	 * {@link @fluidframework/core-interfaces#LogLevelConst.info | LogLevel.info}) through the shared
+	 * object's logger, allowing applications to detect which documents actually required healing.
+	 *
 	 * Off by default because enabling it for documents that are not actually corrupt
 	 * would mask genuine bugs that otherwise surface as decode failures.
 	 *
@@ -739,12 +750,26 @@ export const ForestTypeOptimized = toForestType(
  * Includes validation with scales poorly.
  * May be asymptotically slower than {@link ForestTypeReference}, and may perform very badly with larger data sizes.
  * @privateRemarks
- * The "ObjectForest" forest type with expensive asserts for debugging.
+ * A {@link ComparisonForest} which uses the "ChunkedForest" forest type as its main forest and validates every delta
+ * against a reference "ObjectForest" (with expensive asserts enabled for schema validation).
+ * This exercises the optimized forest while asserting that its contents stay consistent with the reference implementation.
  * @beta
  */
 export const ForestTypeExpensiveDebug = toForestType(
-	(breaker: Breakable, schema: TreeStoredSchemaSubscription) =>
-		buildForest(breaker, schema, undefined, true),
+	(
+		breaker: Breakable,
+		schema: TreeStoredSchemaSubscription,
+		idCompressor: IIdCompressor,
+		shouldEncodeIncrementally: IncrementalEncodingPolicy,
+	) =>
+		new ComparisonForest(
+			buildChunkedForest(
+				makeTreeChunker(schema, defaultSchemaPolicy, shouldEncodeIncrementally),
+				undefined,
+				idCompressor,
+			),
+			buildForest(breaker, schema, undefined, true),
+		),
 );
 
 type ForestFactory = (

package/src/shared-tree/sharedTreeChangeCodecs.ts

@@ -16,7 +16,11 @@ import {
 	makeCodecFamily,
 	withSchemaValidation,
 } from "../codec/index.js";
-import type { ChangeEncodingContext, TreeStoredSchema } from "../core/index.js";
+import type {
+	ChangeEncodingContext,
+	ChangeDecodingContext,
+	TreeStoredSchema,
+} from "../core/index.js";
 import {
 	ModularChangeFormatVersion,
 	type ModularChangeset,
@@ -39,9 +43,13 @@ import {
 import type { SharedTreeChange, SharedTreeInnerChange } from "./sharedTreeChangeTypes.js";
 
 export function makeSharedTreeChangeCodecFamily(
-	modularChangeCodecFamily: ICodecFamily<ModularChangeset, ChangeEncodingContext>,
+	modularChangeCodecFamily: ICodecFamily<
+		ModularChangeset,
+		ChangeEncodingContext,
+		ChangeDecodingContext
+	>,
 	options: CodecWriteOptions,
-): ICodecFamily<SharedTreeChange, ChangeEncodingContext> {
+): ICodecFamily<SharedTreeChange, ChangeEncodingContext, ChangeDecodingContext> {
 	const versions: [
 		FormatVersion,
 		IJsonCodec<

package/src/shared-tree/sharedTreeChangeFamily.ts

@@ -9,6 +9,7 @@ import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type { CodecWriteOptions, ICodecFamily } from "../codec/index.js";
 import {
 	type ChangeEncodingContext,
+	type ChangeDecodingContext,
 	type ChangeFamily,
 	type ChangeRebaser,
 	type DeltaDetachedNodeId,
@@ -18,6 +19,7 @@ import {
 	type RevisionTagCodec,
 	type TaggedChange,
 	mapTaggedChange,
+	type ProcessChangeFn,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -41,6 +43,10 @@ import { makeSharedTreeChangeCodecFamily } from "./sharedTreeChangeCodecs.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 
+export interface SharedTreeChangeProcessingContext {
+	modularChangeFamily: ModularChangeFamily;
+}
+
 /**
  * Implementation of {@link ChangeFamily} that combines edits to fields and schema changes.
  *
@@ -48,14 +54,18 @@ import { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
  */
 export class SharedTreeChangeFamily
 	implements
-		ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>,
+		ChangeFamily<SharedTreeEditBuilder, SharedTreeChange, SharedTreeChangeProcessingContext>,
 		ChangeRebaser<SharedTreeChange>
 {
 	public static readonly emptyChange: SharedTreeChange = {
 		changes: [],
 	};
 
-	public readonly codecs: ICodecFamily<SharedTreeChange, ChangeEncodingContext>;
+	public readonly codecs: ICodecFamily<
+		SharedTreeChange,
+		ChangeEncodingContext,
+		ChangeDecodingContext
+	>;
 	private readonly modularChangeFamily: ModularChangeFamily;
 
 	public constructor(
@@ -94,6 +104,15 @@ export class SharedTreeChangeFamily
 		);
 	}
 
+	public buildProcessor(
+		processFn: ProcessChangeFn<SharedTreeChange, SharedTreeChangeProcessingContext>,
+	): (change: SharedTreeChange) => SharedTreeChange {
+		return (change: SharedTreeChange) =>
+			processFn(change, {
+				modularChangeFamily: this.modularChangeFamily,
+			});
+	}
+
 	public compose(changes: TaggedChange<SharedTreeChange>[]): SharedTreeChange {
 		const newChanges: Mutable<SharedTreeChange["changes"]> = [];
 		const dataChangeRun: TaggedChange<ModularChangeset>[] = [];
@@ -342,3 +361,59 @@ export function updateRefreshers(
 		}
 	});
 }
+
+/**
+ * The status of a {@link SharedTreeChange} with respect to its constraints.
+ */
+export enum ConstraintStatus {
+	/**
+	 * All constraints are satisfied.
+	 */
+	Satisfied,
+	/**
+	 * At least one implicit constraint has been violated.
+	 * @remarks
+	 * Implicit constraints are those that are automatically enforced by SharedTree on all changes.
+	 *
+	 * Such a violation typically arises in one of two scenarios:
+	 * 1. A schema change conflicts with a concurrent data or schema change that was sequenced before it.
+	 * 2. A data change conflicts with a concurrent schema change that was sequenced before it.
+	 */
+	ImplicitViolation,
+	/**
+	 * At least one explicit constraint has been violated.
+	 * @remarks
+	 * Explicit constraints are those that are explicitly added
+	 * through {@link RunTransactionParamsAlpha.preconditions | preconditions}
+	 * or {@link TransactionCallbackStatusAlpha.preconditionsOnRevert | preconditionsOnRevert}.
+	 */
+	ExplicitViolation,
+}
+
+/**
+ * Gets the constraint status of a shared tree change.
+ * @param change - The shared tree change to evaluate.
+ * @returns The constraint status of the change.
+ */
+export function getConstraintStatus(change: SharedTreeChange): ConstraintStatus {
+	if (change.changes.length === 0) {
+		// The SharedTreeChange format (both in memory and over the wire) has no way to convey implicit constraint violation.
+		// Instead, the current rebase implementation in SharedTreeChangeFamily produces an empty change.
+		// This is not ideal because there is no guarantee that an empty change didn't just start out that way.
+		// There is currently only one way to generate an empty change that isn't a result of an implicit constraint violation:
+		// when the SharedTreeChangeFamily is wrapped in makeMitigatedChangeFamily, an empty change is produced when an error occurs.
+		// This is unlikely to cause problems for this logic for two reasons:
+		// 1. Such an error will put SharedTree into a broken state, halting further operations.
+		// 2. It is reasonable to treat a changeset whose production triggered an error as having violated the implicit constraints in our code.
+		return ConstraintStatus.ImplicitViolation;
+	}
+	if (
+		change.changes.some(
+			({ type, innerChange }) =>
+				type === "data" && (innerChange.constraintViolationCount ?? 0) > 0,
+		)
+	) {
+		return ConstraintStatus.ExplicitViolation;
+	}
+	return ConstraintStatus.Satisfied;
+}

package/src/shared-tree/transactionMinimize.ts

@@ -5,13 +5,14 @@
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { fieldKinds, minimizeModularChangeset } from "../feature-libraries/index.js";
+import { minimizeModularChangeset } from "../feature-libraries/index.js";
 import { ChangeProcessorApplicability } from "../shared-tree-core/index.js";
 import type { TransactionPostProcessor } from "../simple-tree/index.js";
 
 import { mapDataChanges } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import { createTransactionPostProcessor } from "./transactionPostProcessor.js";
+import type { SharedTreeChangeProcessingContext } from "./sharedTreeChangeFamily.js";
 
 /**
  * "Minimizes" a {@link SharedTreeChange} so that it contains no extraneous
@@ -26,7 +27,10 @@ import { createTransactionPostProcessor } from "./transactionPostProcessor.js";
  *
  * Schema changes are left unchanged.
  */
-function minimizeSharedTreeChange(change: SharedTreeChange): SharedTreeChange {
+function minimizeSharedTreeChange(
+	change: SharedTreeChange,
+	context: SharedTreeChangeProcessingContext,
+): SharedTreeChange {
 	const countOfDataChanges = change.changes.filter(
 		(innerChange) => innerChange.type === "data",
 	).length;
@@ -36,7 +40,7 @@ function minimizeSharedTreeChange(change: SharedTreeChange): SharedTreeChange {
 		);
 	}
 	return mapDataChanges(change, (dataChange) =>
-		minimizeModularChangeset(dataChange, fieldKinds),
+		minimizeModularChangeset(dataChange, context.modularChangeFamily),
 	);
 }
 

package/src/shared-tree/transactionPostProcessor.ts

@@ -5,6 +5,7 @@
 
 import type { ChangeProcessor } from "../shared-tree-core/index.js";
 import type { TransactionPostProcessor } from "../simple-tree/index.js";
+import type { SharedTreeChangeProcessingContext } from "./sharedTreeChangeFamily.js";
 
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 
@@ -13,7 +14,10 @@ import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
  * {@link SharedTreeChange}.
  * @remarks This is the (non-type-erased) form used internally to apply a transaction's post-processor.
  */
-export type TransactionPostProcessorInternal = ChangeProcessor<SharedTreeChange>;
+export type TransactionPostProcessorInternal = ChangeProcessor<
+	SharedTreeChange,
+	SharedTreeChangeProcessingContext
+>;
 
 /**
  * Type-erases an internal {@link TransactionPostProcessorInternal | change processor} as a public

package/src/shared-tree/treeCheckout.ts

@@ -4,7 +4,11 @@
  */
 
 import { createEmitter } from "@fluid-internal/client-utils";
-import type { IFluidHandle, Listenable } from "@fluidframework/core-interfaces/internal";
+import type {
+	IEmitter,
+	IFluidHandle,
+	Listenable,
+} from "@fluidframework/core-interfaces/internal";
 import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 import { type TelemetryLoggerExt, UsageError } from "@fluidframework/telemetry-utils/internal";
@@ -21,6 +25,7 @@ import {
 	type AnchorSetRootEvents,
 	type ChangeFamily,
 	CommitKind,
+	CommitOutcome,
 	type DeltaVisitor,
 	type DetachedFieldIndex,
 	type IEditableForest,
@@ -57,6 +62,7 @@ import {
 	deltaFieldMapHasVisibleChanges,
 	findCommonAncestor,
 	rebaseBranch,
+	type LocalCommitEvents,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -114,7 +120,13 @@ import {
 
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import { SharedTreeChangeEnricher } from "./sharedTreeChangeEnricher.js";
-import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamily.js";
+import type { SharedTreeChangeProcessingContext } from "./sharedTreeChangeFamily.js";
+import {
+	ConstraintStatus,
+	SharedTreeChangeFamily,
+	getConstraintStatus,
+	hasSchemaChange,
+} from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { extractTransactionChangeProcessor } from "./transactionPostProcessor.js";
@@ -210,7 +222,9 @@ export interface CheckoutEvents {
 /**
  * A collection of functions for managing transactions on a {@link ITreeCheckout}.
  */
-export type TreeTransactor = Transactor<SquashingTransactionOptions<SharedTreeChange>>;
+export type TreeTransactor = Transactor<
+	SquashingTransactionOptions<SharedTreeChange, SharedTreeChangeProcessingContext>
+>;
 
 /**
  * Provides a means for interacting with a SharedTree.
@@ -305,8 +319,16 @@ export function createTreeCheckout(
 	mintRevisionTag: () => RevisionTag,
 	revisionTagCodec: RevisionTagCodec,
 	args?: {
-		branch?: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>;
-		changeFamily?: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>;
+		branch?: SharedTreeBranch<
+			SharedTreeEditBuilder,
+			SharedTreeChange,
+			SharedTreeChangeProcessingContext
+		>;
+		changeFamily?: ChangeFamily<
+			SharedTreeEditBuilder,
+			SharedTreeChange,
+			SharedTreeChangeProcessingContext
+		>;
 		schema?: TreeStoredSchemaRepository;
 		forest?: IEditableForest;
 		fieldBatchCodec?: FieldBatchCodec;
@@ -489,6 +511,14 @@ export class TreeCheckout implements ITreeCheckout {
 
 	private readonly views = new Set<TreeView<ImplicitFieldSchema>>();
 
+	/**
+	 * Event emitters for local commits.
+	 */
+	private readonly localCommitEventEmitters = new Map<
+		RevisionTag,
+		IEmitter<LocalCommitEvents>
+	>();
+
 	/**
 	 * Revertibles maintained for automatic disposal
 	 */
@@ -501,7 +531,11 @@ export class TreeCheckout implements ITreeCheckout {
 	 */
 	private readonly revertibleCommitBranches = new Map<
 		RevisionTag,
-		SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>
+		SharedTreeBranch<
+			SharedTreeEditBuilder,
+			SharedTreeChange,
+			SharedTreeChangeProcessingContext
+		>
 	>();
 
 	/**
@@ -514,20 +548,24 @@ export class TreeCheckout implements ITreeCheckout {
 	public events: Listenable<CheckoutEvents> = this.#events;
 
 	public constructor(
-		branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,
+		branch: SharedTreeBranch<
+			SharedTreeEditBuilder,
+			SharedTreeChange,
+			SharedTreeChangeProcessingContext
+		>,
 		/** True if and only if this checkout is for a branch which is persisted and shared with other clients. */
 		public readonly isSharedBranch: boolean,
-		private readonly changeFamily: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>,
+		private readonly changeFamily: ChangeFamily<
+			SharedTreeEditBuilder,
+			SharedTreeChange,
+			SharedTreeChangeProcessingContext
+		>,
 		public readonly storedSchema: TreeStoredSchemaRepository,
 		public readonly forest: IEditableForest,
 		private readonly mintRevisionTag: () => RevisionTag,
 		private readonly revisionTagCodec: RevisionTagCodec,
 		private readonly idCompressor: IIdCompressor,
-		private readonly _removedRoots: DetachedFieldIndex = makeDetachedFieldIndex(
-			"repair",
-			revisionTagCodec,
-			idCompressor,
-		),
+		private readonly _removedRoots: DetachedFieldIndex = makeDetachedFieldIndex("repair"),
 		/** Optional logger for telemetry. */
 		private readonly logger?: TelemetryLoggerExt,
 		public readonly breaker: Breakable = new Breakable("TreeCheckout", logger),
@@ -649,19 +687,29 @@ export class TreeCheckout implements ITreeCheckout {
 
 	private registerForBranchEvents(): void {
 		this.#transaction.branch.events.on("afterChange", this.onAfterBranchChange);
+		this.#transaction.branch.events.on("commitSequenced", this.onCommitSequenced);
 		this.#transaction.activeBranchEvents.on("afterChange", this.onAfterChange);
 		this.#transaction.activeBranchEvents.on("ancestryTrimmed", this.onAncestryTrimmed);
 	}
 
 	private unregisterFromBranchEvents(): void {
 		this.#transaction.branch.events.off("afterChange", this.onAfterBranchChange);
+		this.#transaction.branch.events.off("commitSequenced", this.onCommitSequenced);
 		this.#transaction.activeBranchEvents.off("afterChange", this.onAfterChange);
 		this.#transaction.activeBranchEvents.off("ancestryTrimmed", this.onAncestryTrimmed);
 	}
 
 	private createTransactionStack(
-		branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,
-	): SquashingTransactionStack<SharedTreeEditBuilder, SharedTreeChange> {
+		branch: SharedTreeBranch<
+			SharedTreeEditBuilder,
+			SharedTreeChange,
+			SharedTreeChangeProcessingContext
+		>,
+	): SquashingTransactionStack<
+		SharedTreeEditBuilder,
+		SharedTreeChange,
+		SharedTreeChangeProcessingContext
+	> {
 		return new SquashingTransactionStack(branch, this.mintRevisionTag, () => {
 			// When each transaction is started, make a restorable checkpoint of the current state of removed roots
 			const restoreRemovedRoots = this._removedRoots.createCheckpoint();
@@ -712,6 +760,39 @@ export class TreeCheckout implements ITreeCheckout {
 		}
 	}
 
+	private readonly onCommitSequenced = (commit: GraphCommit<SharedTreeChange>): void => {
+		const emitter = this.localCommitEventEmitters.get(commit.revision);
+		if (emitter === undefined) {
+			// If the commit predates the creation of this checkout, there will be no emitter associated with the commit.
+			// In that case, we don't need to emit any events.
+			return;
+		}
+		const constraintStatus = getConstraintStatus(commit.change);
+		let outcome: CommitOutcome;
+		switch (constraintStatus) {
+			case ConstraintStatus.Satisfied: {
+				outcome = CommitOutcome.FullyApplied;
+				break;
+			}
+			case ConstraintStatus.ImplicitViolation: {
+				outcome = CommitOutcome.FullyDropped;
+				break;
+			}
+			case ConstraintStatus.ExplicitViolation: {
+				outcome = CommitOutcome.NewContentOnly;
+				break;
+			}
+			default: {
+				unreachableCase(constraintStatus);
+			}
+		}
+		this.emitChangedLocked(() => {
+			emitter.emit("settled", outcome);
+		}, "a commit settled event callback");
+		// No more events will be emitted for this commit, so we can remove the emitter from the map.
+		this.localCommitEventEmitters.delete(commit.revision);
+	};
+
 	private readonly onAfterBranchChange = (
 		event: SharedTreeBranchChange<SharedTreeChange>,
 	): void => {
@@ -760,6 +841,8 @@ export class TreeCheckout implements ITreeCheckout {
 
 				let withinEventContext = true;
 
+				const events = createEmitter<LocalCommitEvents>();
+				this.localCommitEventEmitters.set(commit.revision, events);
 				const metadata: ChangeMetadata = {
 					kind,
 					isLocal: true,
@@ -778,6 +861,7 @@ export class TreeCheckout implements ITreeCheckout {
 					getRevertible: (onDisposed) => getRevertible?.(onDisposed),
 					label: this.labelTreeNode?.label,
 					labels: buildLabelsSet(this.labelTreeNode),
+					events,
 				};
 
 				this.emitChangedLocked(() => {
@@ -811,8 +895,11 @@ export class TreeCheckout implements ITreeCheckout {
 	 * Shared by both the local and remote `changed` emission paths in {@link TreeCheckout.onAfterBranchChange}.
 	 * The `try`/`finally` ensures the lock is released even if a listener throws.
 	 */
-	private emitChangedLocked(emit: () => void): void {
-		this.editLock.lock();
+	private emitChangedLocked(
+		emit: () => void,
+		reason: string = "a change event callback",
+	): void {
+		this.editLock.lock(reason);
 		try {
 			emit();
 		} finally {
@@ -828,7 +915,7 @@ export class TreeCheckout implements ITreeCheckout {
 	}
 
 	private readonly onAfterChange = (event: SharedTreeBranchChange<SharedTreeChange>): void => {
-		this.editLock.lock();
+		this.editLock.lock("a change event callback");
 		this.#events.emit("beforeBatch", event);
 		if (event.change !== undefined) {
 			const revision =
@@ -1187,7 +1274,11 @@ export class TreeCheckout implements ITreeCheckout {
 	 * To avoid updating observers of the view state with intermediate results during a transaction,
 	 * use {@link ITreeCheckout#fork} and {@link ISharedTreeFork#merge}.
 	 */
-	#transaction: SquashingTransactionStack<SharedTreeEditBuilder, SharedTreeChange>;
+	#transaction: SquashingTransactionStack<
+		SharedTreeEditBuilder,
+		SharedTreeChange,
+		SharedTreeChangeProcessingContext
+	>;
 
 	@throwIfBroken
 	public fork(): TreeCheckout {
@@ -1221,7 +1312,11 @@ export class TreeCheckout implements ITreeCheckout {
 	}
 
 	public switchBranch(
-		branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,
+		branch: SharedTreeBranch<
+			SharedTreeEditBuilder,
+			SharedTreeChange,
+			SharedTreeChangeProcessingContext
+		>,
 	): void {
 		// TODO: Dispose old branch, if necessary
 		assert(
@@ -1648,7 +1743,11 @@ export class TreeCheckout implements ITreeCheckout {
 		return enriched;
 	}
 
-	public get mainBranch(): SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange> {
+	public get mainBranch(): SharedTreeBranch<
+		SharedTreeEditBuilder,
+		SharedTreeChange,
+		SharedTreeChangeProcessingContext
+	> {
 		return this.#transaction.branch;
 	}
 
@@ -1664,7 +1763,13 @@ class EditLock {
 	 * @remarks Edits will throw an error if the lock is currently locked.
 	 */
 	public readonly editor: ISharedTreeEditor;
-	private locked = false;
+	/**
+	 * The current status of the lock.
+	 * The `reason` string will be included in the error message if an attempt is made to edit the tree while the lock is held.
+	 */
+	private status:
+		| { readonly isLocked: false }
+		| { readonly isLocked: true; readonly reason: string } = { isLocked: false };
 
 	/**
 	 * @param editor - an editor which will be used to create a new editor that is monitored to determine if any changes are happening to the tree.
@@ -1728,14 +1833,15 @@ class EditLock {
 
 	/**
 	 * Prevent further changes from being made to {@link EditLock.editor} until {@link EditLock.unlock} is called.
+	 * @param reason - A string describing why the lock is being acquired. This will be included in the error message if an attempt is made to edit while the lock is held.
 	 * @remarks May only be called when the lock is not already locked.
 	 */
-	public lock(): void {
-		if (this.locked) {
+	public lock(reason: string): void {
+		if (this.status.isLocked) {
 			debugger;
 		}
-		assert(!this.locked, 0xaa7 /* Checkout has already been locked */);
-		this.locked = true;
+		assert(!this.status.isLocked, 0xaa7 /* Checkout has already been locked */);
+		this.status = { isLocked: true, reason };
 	}
 
 	/**
@@ -1744,8 +1850,8 @@ class EditLock {
 	 * This must start with a capital letter, as it shows up as the first part of the error message and we want it to look nice.
 	 */
 	public checkUnlocked<T extends string>(action: T extends Capitalize<T> ? T : never): void {
-		if (this.locked) {
-			throw new UsageError(`${action} is forbidden during a change event callback`);
+		if (this.status.isLocked) {
+			throw new UsageError(`${action} is forbidden during ${this.status.reason}`);
 		}
 	}
 
@@ -1754,8 +1860,8 @@ class EditLock {
 	 * @remarks May only be called when the lock is currently locked.
 	 */
 	public unlock(): void {
-		assert(this.locked, 0xaa8 /* Checkout has not been locked */);
-		this.locked = false;
+		assert(this.status.isLocked, 0xaa8 /* Checkout has not been locked */);
+		this.status = { isLocked: false };
 	}
 }