@fluidframework/tree 2.12.0 → 2.20.0

package/src/shared-tree/sharedTree.ts

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
-import type { IFluidHandle } from "@fluidframework/core-interfaces/internal";
+import { assert } from "@fluidframework/core-utils/internal";
+import type { ErasedType, IFluidHandle } from "@fluidframework/core-interfaces/internal";
 import type {
 	IChannelAttributes,
 	IChannelFactory,
@@ -186,30 +186,6 @@ function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
 	return versions;
 }
 
-/**
- * Build and return a forest of the requested type.
- */
-export function buildConfiguredForest(
-	type: ForestType,
-	schema: TreeStoredSchemaSubscription,
-	idCompressor: IIdCompressor,
-): IEditableForest {
-	switch (type) {
-		case ForestType.Optimized:
-			return buildChunkedForest(
-				makeTreeChunker(schema, defaultSchemaPolicy),
-				undefined,
-				idCompressor,
-			);
-		case ForestType.Reference:
-			return buildForest();
-		case ForestType.Expensive:
-			return buildForest(undefined, true);
-		default:
-			unreachableCase(type);
-	}
-}
-
 /**
  * Shared tree, configured with a good set of indexes and field kinds which will maintain compatibility over time.
  *
@@ -229,7 +205,7 @@ export class SharedTree
 		id: string,
 		runtime: IFluidDataStoreRuntime,
 		attributes: IChannelAttributes,
-		optionsParam: SharedTreeOptions,
+		optionsParam: SharedTreeOptionsInternal,
 		telemetryContextPrefix: string = "fluid_sharedTree_",
 	) {
 		if (runtime.idCompressor === undefined) {
@@ -333,6 +309,7 @@ export class SharedTree
 				chunkCompressionStrategy: options.treeEncodeType,
 				logger: this.logger,
 				breaker: this.breaker,
+				disposeForksAfterTransaction: options.disposeForksAfterTransaction,
 			},
 		);
 
@@ -459,7 +436,7 @@ export class SharedTree
 	): void {
 		assert(
 			!this.checkout.transaction.isInProgress(),
-			"Cannot submit a commit while a transaction is in progress",
+			0xaa6 /* Cannot submit a commit while a transaction is in progress */,
 		);
 		if (isResubmit) {
 			return super.submitCommit(commit, schemaAndPolicy, isResubmit);
@@ -555,6 +532,9 @@ export type SharedTreeOptions = Partial<ICodecOptions> &
 	Partial<SharedTreeFormatOptions> &
 	ForestOptions;
 
+export interface SharedTreeOptionsInternal extends SharedTreeOptions {
+	disposeForksAfterTransaction?: boolean;
+}
 /**
  * Configuration options for SharedTree's internal tree storage.
  * @alpha
@@ -592,28 +572,73 @@ export interface SharedTreeFormatOptions {
 
 /**
  * Used to distinguish between different forest types.
+ * @remarks
+ * Current options are {@link ForestTypeReference}, {@link ForestTypeOptimized} and {@link ForestTypeExpensiveDebug}.
+ * @sealed @alpha
+ */
+export interface ForestType extends ErasedType<"ForestType"> {}
+
+/**
+ * Reference implementation of forest.
+ * @remarks
+ * A simple implementation with minimal complexity and moderate debuggability, validation and performance.
+ * @privateRemarks
+ * The "ObjectForest" forest type.
  * @alpha
  */
-export enum ForestType {
-	/**
-	 * The "ObjectForest" forest type.
-	 */
-	Reference = 0,
-	/**
-	 * The "ChunkedForest" forest type.
-	 */
-	Optimized = 1,
-	/**
-	 * The "ObjectForest" forest type with expensive asserts for debugging.
-	 */
-	Expensive = 2,
+export const ForestTypeReference = toForestType(() => buildForest());
+
+/**
+ * Optimized implementation of forest.
+ * @remarks
+ * A complex optimized forest implementation, which has minimal validation and debuggability to optimize for performance.
+ * Uses an internal representation optimized for size designed to scale to larger datasets with reduced overhead.
+ * @privateRemarks
+ * The "ChunkedForest" forest type.
+ * @alpha
+ */
+export const ForestTypeOptimized = toForestType(
+	(schema: TreeStoredSchemaSubscription, idCompressor: IIdCompressor) =>
+		buildChunkedForest(makeTreeChunker(schema, defaultSchemaPolicy), undefined, idCompressor),
+);
+
+/**
+ * Slow implementation of forest intended only for debugging.
+ * @remarks
+ * 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.
+ * @alpha
+ */
+export const ForestTypeExpensiveDebug = toForestType(() => buildForest(undefined, true));
+
+type ForestFactory = (
+	schema: TreeStoredSchemaSubscription,
+	idCompressor: IIdCompressor,
+) => IEditableForest;
+
+function toForestType(factory: ForestFactory): ForestType {
+	return factory as unknown as ForestType;
+}
+
+/**
+ * Build and return a forest of the requested type.
+ */
+export function buildConfiguredForest(
+	factory: ForestType,
+	schema: TreeStoredSchemaSubscription,
+	idCompressor: IIdCompressor,
+): IEditableForest {
+	return (factory as unknown as ForestFactory)(schema, idCompressor);
 }
 
-export const defaultSharedTreeOptions: Required<SharedTreeOptions> = {
+export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	jsonValidator: noopValidator,
-	forest: ForestType.Reference,
+	forest: ForestTypeReference,
 	treeEncodeType: TreeCompressionStrategy.Compressed,
 	formatVersion: SharedTreeFormatVersion.v3,
+	disposeForksAfterTransaction: true,
 };
 
 /**
@@ -628,7 +653,7 @@ export class SharedTreeFactory implements IChannelFactory<ISharedTree> {
 		packageVersion: "0.0.0",
 	};
 
-	public constructor(private readonly options: SharedTreeOptions = {}) {}
+	public constructor(private readonly options: SharedTreeOptionsInternal = {}) {}
 
 	public async load(
 		runtime: IFluidDataStoreRuntime,

package/src/shared-tree/transactionTypes.ts

@@ -0,0 +1,125 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { TreeNode } from "../simple-tree/index.js";
+
+/**
+ * A special object that signifies when a SharedTree {@link RunTransaction | transaction} should "roll back".
+ * @public
+ */
+export const rollback = Symbol("SharedTree Transaction Rollback");
+
+/**
+ * A requirement for a SharedTree transaction to succeed.
+ * @remarks Transaction constraints are useful for validating that the state of the tree meets some requirement when a transaction runs.
+ * In general, when running a transaction a client can validate their tree state in whatever way they wish and decide to either proceed with the transaction or not.
+ * However, they cannot know what the tree state will be when the transaction is _sequenced_.
+ * There may have been any number of edits from other clients that get sequenced before the transaction is eventually sequenced.
+ * Constraints provide a way to validate the tree state after the transaction has been sequenced and abort the transaction if the constraints are not met.
+ * All clients will validate the constraints of a transaction when it is sequenced, so all clients will agree on whether the transaction succeeds or not.
+ * @public
+ */
+export type TransactionConstraint = NodeInDocumentConstraint; // TODO: Add more constraint types here
+
+/**
+ * A transaction {@link TransactionConstraint | constraint} which requires that the given node exists in the tree.
+ * @remarks The node must be in the document (its {@link TreeStatus | status} must be {@link TreeStatus.InDocument | InDocument}) to qualify as "existing".
+ * @public
+ */
+export interface NodeInDocumentConstraint {
+	readonly type: "nodeInDocument";
+	readonly node: TreeNode;
+}
+
+/**
+ * The status of the transaction callback in the {@link RunTransaction | RunTransaction} API.
+ * @alpha
+ */
+export type TransactionCallbackStatus<TSuccessValue, TFailureValue> = (
+	| {
+			/** Indicates that the transaction callback ran successfully. */
+			rollback?: false;
+			/** The user defined value when the transaction ran successfully. */
+			value: TSuccessValue;
+	  }
+	| {
+			/** Indicates that the transaction callback failed and the transaction should be rolled back. */
+			rollback: true;
+			/** The user defined value when the transaction failed. */
+			value: TFailureValue;
+	  }
+) & {
+	/**
+	 * An optional list of {@link TransactionConstraint | constraints} that will be checked when the commit corresponding
+	 * to this transaction is reverted. If any of these constraints are not met when the revert is being applied either
+	 * locally or on remote clients, the revert will be ignored.
+	 * These constraints must also be met at the time they are first introduced. If they are not met after the transaction
+	 * callback returns, then `runTransaction` (which invokes the transaction callback) will throw a `UsageError`.
+	 */
+	preconditionsOnRevert?: readonly TransactionConstraint[];
+};
+
+/**
+ * The status of a the transaction callback in the {@link RunTransaction | RunTransaction} API where the transaction doesn't
+ * need to return a value. This is the same as {@link TransactionCallbackStatus} but with the `value` field omitted. This
+ * @alpha
+ */
+export type VoidTransactionCallbackStatus = Omit<
+	TransactionCallbackStatus<unknown, unknown>,
+	"value"
+>;
+
+/**
+ * The result of the {@link RunTransaction | RunTransaction} API when it was successful.
+ * @alpha
+ */
+export interface TransactionResultSuccess<TSuccessValue> {
+	/** Indicates that the transaction was successful. */
+	success: true;
+	/** The user defined value when the transaction was successful. */
+	value: TSuccessValue;
+}
+
+/**
+ * The result of the {@link RunTransaction | RunTransaction} API when it failed.
+ * @alpha
+ */
+export interface TransactionResultFailed<TFailureValue> {
+	/** Indicates that the transaction failed. */
+	success: false;
+	/** The user defined value when the transaction failed. */
+	value: TFailureValue;
+}
+
+/**
+ * The result of the {@link RunTransaction | RunTransaction} API.
+ * @alpha
+ */
+export type TransactionResultExt<TSuccessValue, TFailureValue> =
+	| TransactionResultSuccess<TSuccessValue>
+	| TransactionResultFailed<TFailureValue>;
+
+/**
+ * The result of the {@link RunTransaction | RunTransaction} API. This is the same as {@link TransactionResultExt}
+ * but with the `value` field omitted. This is useful when the transaction callback doesn't need to return a value.
+ * @alpha
+ */
+export type TransactionResult =
+	| Omit<TransactionResultSuccess<unknown>, "value">
+	| Omit<TransactionResultFailed<unknown>, "value">;
+
+/**
+ * The parameters for the {@link RunTransaction | RunTransaction} API.
+ * @alpha
+ */
+export interface RunTransactionParams {
+	/**
+	 * An optional list of {@link TransactionConstraint | constraints} that are checked just before the transaction begins.
+	 * If any of the constraints are not met when `runTransaction` is called, an error will be thrown.
+	 * If any of the constraints are not met after the transaction has been ordered by the service, it will be rolled back on
+	 * this client and ignored by all other clients.
+	 */
+	readonly preconditions?: readonly TransactionConstraint[];
+}

package/src/shared-tree/treeApi.ts

@@ -19,12 +19,7 @@ import {
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import type { ITreeCheckout } from "./treeCheckout.js";
 import { getCheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
-
-/**
- * A special object that signifies when a SharedTree {@link RunTransaction | transaction} should "roll back".
- * @public
- */
-export const rollback = Symbol("SharedTree Transaction Rollback");
+import { rollback, type TransactionConstraint } from "./transactionTypes.js";
 
 /**
  * A function which runs a transaction in a SharedTree.
@@ -380,28 +375,6 @@ export const treeApi: TreeApi = {
 	},
 };
 
-/**
- * A requirement for a SharedTree transaction to succeed.
- * @remarks Transaction constraints are useful for validating that the state of the tree meets some requirement when a transaction runs.
- * In general, when running a transaction a client can validate their tree state in whatever way they wish and decide to either proceed with the transaction or not.
- * However, they cannot know what the tree state will be when the transaction is _sequenced_.
- * There may have been any number of edits from other clients that get sequenced before the transaction is eventually sequenced.
- * Constraints provide a way to validate the tree state after the transaction has been sequenced and abort the transaction if the constraints are not met.
- * All clients will validate the constraints of a transaction when it is sequenced, so all clients will agree on whether the transaction succeeds or not.
- * @public
- */
-export type TransactionConstraint = NodeInDocumentConstraint; // TODO: Add more constraint types here
-
-/**
- * A transaction {@link TransactionConstraint | constraint} which requires that the given node exists in the tree.
- * @remarks The node must be in the document (its {@link TreeStatus | status} must be {@link TreeStatus.InDocument | InDocument}) to qualify as "existing".
- * @public
- */
-export interface NodeInDocumentConstraint {
-	readonly type: "nodeInDocument";
-	readonly node: TreeNode;
-}
-
 // TODO: Add more constraint types here
 
 /** Creates a copy of `runTransaction` with the `rollback` property added so as to satisfy the `RunTransaction` interface. */

package/src/shared-tree/treeCheckout.ts

@@ -41,6 +41,7 @@ import {
 	type RevertibleAlphaFactory,
 	type RevertibleAlpha,
 	type GraphCommit,
+	isAncestor,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -73,6 +74,7 @@ import type {
 	UnsafeUnknownSchema,
 	ViewableTree,
 	TreeBranch,
+	TreeChangeEvents,
 } from "../simple-tree/index.js";
 import { getCheckout, SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 
@@ -271,6 +273,7 @@ export function createTreeCheckout(
 		chunkCompressionStrategy?: TreeCompressionStrategy;
 		logger?: ITelemetryLoggerExt;
 		breaker?: Breakable;
+		disposeForksAfterTransaction?: boolean;
 	},
 ): TreeCheckout {
 	const forest = args?.forest ?? buildForest();
@@ -310,6 +313,7 @@ export function createTreeCheckout(
 		args?.removedRoots,
 		args?.logger,
 		args?.breaker,
+		args?.disposeForksAfterTransaction,
 	);
 }
 
@@ -342,6 +346,8 @@ export interface RevertMetrics {
 export class TreeCheckout implements ITreeCheckoutFork {
 	public disposed = false;
 
+	private readonly editLock: EditLock;
+
 	private readonly views = new Set<TreeView<ImplicitFieldSchema>>();
 
 	/**
@@ -386,6 +392,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		/** Optional logger for telemetry. */
 		private readonly logger?: ITelemetryLoggerExt,
 		private readonly breaker: Breakable = new Breakable("TreeCheckout"),
+		private readonly disposeForksAfterTransaction = true,
 	) {
 		this.#transaction = new SquashingTransactionStack(
 			branch,
@@ -400,14 +407,9 @@ export class TreeCheckout implements ITreeCheckoutFork {
 				return tagChange(change, revision);
 			},
 			() => {
-				// Keep track of all the forks created during the transaction so that we can dispose them when the transaction ends.
-				// This is a policy decision that we think is useful for the user, but it is not necessary for correctness.
-				const forks = new Set<TreeCheckout>();
-				const onDisposeUnSubscribes: (() => void)[] = [];
-				const onForkUnSubscribe = onForkTransitive(this, (fork) => {
-					forks.add(fork);
-					onDisposeUnSubscribes.push(fork.events.on("dispose", () => forks.delete(fork)));
-				});
+				const disposeForks = this.disposeForksAfterTransaction
+					? trackForksForDisposal(this)
+					: undefined;
 				// When each transaction is started, take a snapshot of the current state of removed roots
 				const removedRootsSnapshot = this.removedRoots.clone();
 				return (result) => {
@@ -424,14 +426,13 @@ export class TreeCheckout implements ITreeCheckoutFork {
 						default:
 							unreachableCase(result);
 					}
-
-					forks.forEach((fork) => fork.dispose());
-					onDisposeUnSubscribes.forEach((unsubscribe) => unsubscribe());
-					onForkUnSubscribe();
+					disposeForks?.();
 				};
 			},
 		);
 
+		this.editLock = new EditLock(this.#transaction.activeBranchEditor);
+
 		branch.events.on("afterChange", (event) => {
 			// The following logic allows revertibles to be generated for the change.
 			// Currently only appends (including merges and transaction commits) are supported.
@@ -484,6 +485,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	}
 
 	private readonly onAfterChange = (event: SharedTreeBranchChange<SharedTreeChange>): void => {
+		this.editLock.lock();
 		this.#events.emit("beforeBatch", event);
 		if (event.change !== undefined) {
 			const revision =
@@ -521,6 +523,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			}
 		}
 		this.#events.emit("afterBatch");
+		this.editLock.unlock();
 		if (event.type === "append") {
 			event.newCommits.forEach((commit) => this.validateCommit(commit));
 		}
@@ -603,21 +606,27 @@ export class TreeCheckout implements ITreeCheckoutFork {
 					revertible.dispose();
 				}
 			},
-			clone: (forkedBranch: TreeBranch) => {
-				if (forkedBranch === undefined) {
-					return this.createRevertible(revision, kind, checkout, onRevertibleDisposed);
-				}
-
+			clone: (targetBranch: TreeBranch) => {
 				// TODO:#23442: When a revertible is cloned for a forked branch, optimize to create a fork of a revertible branch once per revision NOT once per revision per checkout.
-				const forkedCheckout = getCheckout(forkedBranch);
+				const targetCheckout = getCheckout(targetBranch);
+
 				const revertibleBranch = this.revertibleCommitBranches.get(revision);
-				assert(
-					revertibleBranch !== undefined,
-					0xa82 /* change to revert does not exist on the given forked branch */,
-				);
-				forkedCheckout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
+				if (revertibleBranch === undefined) {
+					throw new UsageError("Unable to clone a revertible that has been disposed.");
+				}
+
+				const commitToRevert = revertibleBranch.getHead();
+				const activeBranchHead = targetCheckout.#transaction.activeBranch.getHead();
+
+				if (isAncestor(commitToRevert, activeBranchHead, true) === false) {
+					throw new UsageError(
+						"Cannot clone revertible for a commit that is not present on the given branch.",
+					);
+				}
+
+				targetCheckout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
 
-				return this.createRevertible(revision, kind, forkedCheckout, onRevertibleDisposed);
+				return this.createRevertible(revision, kind, targetCheckout, onRevertibleDisposed);
 			},
 			dispose: () => {
 				if (revertible.status === RevertibleStatus.Disposed) {
@@ -665,7 +674,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 
 	public get editor(): ISharedTreeEditor {
 		this.checkNotDisposed();
-		return this.#transaction.activeBranchEditor;
+		return this.editLock.editor;
 	}
 
 	public locate(anchor: Anchor): AnchorNode | undefined {
@@ -692,6 +701,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		this.checkNotDisposed(
 			"The parent branch has already been disposed and can no longer create new branches.",
 		);
+		this.editLock.checkUnlocked("Branching");
 		const anchors = new AnchorSet();
 		const branch = this.#transaction.activeBranch.fork();
 		const storedSchema = this.storedSchema.clone();
@@ -708,6 +718,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			this.removedRoots.clone(),
 			this.logger,
 			this.breaker,
+			this.disposeForksAfterTransaction,
 		);
 		this.#events.emit("fork", checkout);
 		return checkout;
@@ -720,6 +731,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		checkout.checkNotDisposed(
 			"The source of the branch rebase has been disposed and cannot be rebased.",
 		);
+		this.editLock.checkUnlocked("Rebasing");
 		assert(
 			!checkout.transaction.isInProgress(),
 			0x9af /* A view cannot be rebased while it has a pending transaction */,
@@ -748,6 +760,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		checkout.checkNotDisposed(
 			"The source of the branch merge has been disposed and cannot be merged.",
 		);
+		this.editLock.checkUnlocked("Merging");
 		assert(
 			!this.transaction.isInProgress(),
 			0x9b0 /* Views cannot be merged into a view while it has a pending transaction */,
@@ -768,6 +781,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	}
 
 	public dispose(): void {
+		this.editLock.checkUnlocked("Disposing a view");
 		this[disposeSymbol]();
 	}
 
@@ -955,3 +969,130 @@ export class TreeCheckout implements ITreeCheckoutFork {
 
 	// #endregion Commit Validation
 }
+
+/**
+ * A helper class that assists {@link TreeCheckout} in preventing functionality from being used while the tree is in the middle of being edited.
+ */
+class EditLock {
+	/**
+	 * Edits the tree by calling the methods of the editor passed into the {@link EditLock} constructor.
+	 * @remarks Edits will throw an error if the lock is currently locked.
+	 */
+	public editor: ISharedTreeEditor;
+	private locked = 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.
+	 * Use {@link EditLock.editor} in place of the original editor to ensure that changes are monitored.
+	 */
+	public constructor(editor: ISharedTreeEditor) {
+		const checkLock = (): void => this.checkUnlocked("Editing the tree");
+		this.editor = {
+			get schema() {
+				return editor.schema;
+			},
+			valueField(...fieldArgs) {
+				const valueField = editor.valueField(...fieldArgs);
+				return {
+					set(...editArgs) {
+						checkLock();
+						valueField.set(...editArgs);
+					},
+				};
+			},
+			optionalField(...fieldArgs) {
+				const optionalField = editor.optionalField(...fieldArgs);
+				return {
+					set(...editArgs) {
+						checkLock();
+						optionalField.set(...editArgs);
+					},
+				};
+			},
+			sequenceField(...fieldArgs) {
+				const sequenceField = editor.sequenceField(...fieldArgs);
+				return {
+					insert(...editArgs) {
+						checkLock();
+						sequenceField.insert(...editArgs);
+					},
+					remove(...editArgs) {
+						checkLock();
+						sequenceField.remove(...editArgs);
+					},
+				};
+			},
+			move(...moveArgs) {
+				checkLock();
+				editor.move(...moveArgs);
+			},
+			addNodeExistsConstraint(path) {
+				editor.addNodeExistsConstraint(path);
+			},
+			addNodeExistsConstraintOnRevert(path) {
+				editor.addNodeExistsConstraintOnRevert(path);
+			},
+		};
+	}
+
+	/**
+	 * Prevent further changes from being made to {@link EditLock.editor} until {@link EditLock.unlock} is called.
+	 * @remarks May only be called when the lock is not already locked.
+	 */
+	public lock(): void {
+		if (this.locked) {
+			debugger;
+		}
+		assert(!this.locked, 0xaa7 /* Checkout has already been locked */);
+		this.locked = true;
+	}
+
+	/**
+	 * Throws an error if the lock is currently locked.
+	 * @param action - The current action being performed by the user.
+	 * 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) {
+			// These type assertions ensure that the event name strings used here match the actual event names
+			const nodeChanged: keyof TreeChangeEvents = "nodeChanged";
+			const treeChanged: keyof TreeChangeEvents = "treeChanged";
+			throw new UsageError(
+				`${action} is forbidden during a ${nodeChanged} or ${treeChanged} event`,
+			);
+		}
+	}
+
+	/**
+	 * Allow changes to be made to {@link EditLock.editor} again.
+	 * @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;
+	}
+}
+
+/**
+ * Keeps track of all new forks created until the returned function is invoked, which will dispose all of those for.
+ * The returned function may only be called once.
+ *
+ * @param checkout - The tree checkout for which you want to monitor forks for disposal.
+ * @returns a function which can be called to dispose all of the tracked forks.
+ */
+function trackForksForDisposal(checkout: TreeCheckout): () => void {
+	const forks = new Set<TreeCheckout>();
+	const onDisposeUnSubscribes: (() => void)[] = [];
+	const onForkUnSubscribe = onForkTransitive(checkout, (fork) => {
+		forks.add(fork);
+		onDisposeUnSubscribes.push(fork.events.on("dispose", () => forks.delete(fork)));
+	});
+	let disposed = false;
+	return () => {
+		assert(!disposed, 0xaa9 /* Forks may only be disposed once */);
+		forks.forEach((fork) => fork.dispose());
+		onDisposeUnSubscribes.forEach((unsubscribe) => unsubscribe());
+		onForkUnSubscribe();
+		disposed = true;
+	};
+}

package/src/shared-tree-core/sharedTreeCore.ts

@@ -259,7 +259,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	protected async loadCore(services: IChannelStorageService): Promise<void> {
 		assert(
 			this.editManager.localBranch.getHead() === this.editManager.getTrunkHead(),
-			"All local changes should be applied to the trunk before loading from summary",
+			0xaaa /* All local changes should be applied to the trunk before loading from summary */,
 		);
 		const [editManagerSummarizer, ...summarizables] = this.summarizables;
 		const loadEditManager = this.loadSummarizable(editManagerSummarizer, services);

package/src/simple-tree/api/index.ts

@@ -22,6 +22,7 @@ export {
 	type ScopedSchemaName,
 	type SchemaFactoryObjectOptions,
 } from "./schemaFactory.js";
+export { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
 export type {
 	ValidateRecursiveSchema,
 	FixRecursiveArraySchema,

package/src/simple-tree/api/jsonSchema.ts

@@ -58,6 +58,13 @@ export interface JsonNodeSchemaBase<
 	 * {@inheritDoc JsonSchemaType}
 	 */
 	readonly type: TJsonSchemaType;
+
+	/**
+	 * Description of the node schema.
+	 * @remarks Derived from {@link NodeSchemaMetadata.description}.
+	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-validation#name-title-and-description}
+	 */
+	readonly description?: string | undefined;
 }
 
 /**