@fluidframework/tree 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

package/src/shared-tree/treeApi.ts

@@ -2,10 +2,20 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { assert } from "@fluidframework/core-utils";
+
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+
+import { Context, TreeStatus } from "../feature-libraries/index.js";
+import {
+	ImplicitFieldSchema,
+	TreeNode,
+	TreeNodeApi,
+	TreeView,
+	getFlexNode,
+	treeNodeApi,
+} from "../simple-tree/index.js";
 import { fail } from "../util/index.js";
-import { Context } from "../feature-libraries/index.js";
-import { TreeNode, TreeNodeApi, TreeView, treeNodeApi, getFlexNode } from "../simple-tree/index.js";
+
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import { TreeCheckout } from "./treeCheckout.js";
 import { contextToTreeView } from "./treeView.js";
@@ -36,12 +46,60 @@ export interface TreeApi extends TreeNodeApi {
 		node: TNode,
 		transaction: (node: TNode) => void | "rollback",
 	): void;
+	/**
+	 * Apply one or more edits to the tree as a single atomic unit.
+	 * @param node - The node that will be passed to `transaction`.
+	 * This is typically the root node of the subtree that will be modified by the transaction.
+	 * @param transaction - The function to run as the body of the transaction.
+	 * This function is passed the provided `node`.
+	 * At any point during the transaction, the function may return the value `"rollback"` to abort the transaction and discard any changes it made so far.
+	 * @param preconditions - 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, it will throw an error.
+	 * If any of the constraints are not met when this transaction is sequenced (on this client or other clients), the transaction will not be run.
+	 * @remarks
+	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
+	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
+	 * However, using a transaction has the following additional consequences:
+	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
+	 *
+	 * Local change events will be emitted for each change as the transaction is being applied.
+	 * If the transaction is cancelled and rolled back, a corresponding change event will also be emitted for the rollback.
+	 */
+	runTransaction<TNode extends TreeNode>(
+		node: TNode,
+		transaction: (node: TNode) => void | "rollback",
+		preconditions?: TransactionConstraint[],
+	): void;
+	/**
+	 * Apply one or more edits to the tree as a single atomic unit.
+	 * @param tree - The tree which will be edited by the transaction
+	 * @param transaction - The function to run as the body of the transaction.
+	 * This function is passed the root of the tree.
+	 * At any point during the transaction, the function may return the value `"rollback"` to abort the transaction and discard any changes it made so far.
+	 * @remarks
+	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
+	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
+	 * However, using a transaction has the following additional consequences:
+	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
+	 *
+	 * Local change events will be emitted for each change as the transaction is being applied.
+	 * If the transaction is cancelled and rolled back, a corresponding change event will also be emitted for the rollback.
+	 */
+	runTransaction<TView extends TreeView<ImplicitFieldSchema>>(
+		tree: TView,
+		transaction: (root: TView["root"]) => void | "rollback",
+	): void;
 	/**
 	 * Apply one or more edits to the tree as a single atomic unit.
 	 * @param tree - The tree which will be edited by the transaction
 	 * @param transaction - The function to run as the body of the transaction.
 	 * This function is passed the root of the tree.
 	 * At any point during the transaction, the function may return the value `"rollback"` to abort the transaction and discard any changes it made so far.
+	 * @param preconditions - 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, it will throw an error.
+	 * If any of the constraints are not met when this transaction is sequenced (on this client or other clients), the transaction will not be run.
 	 * @remarks
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
@@ -52,10 +110,28 @@ export interface TreeApi extends TreeNodeApi {
 	 * Local change events will be emitted for each change as the transaction is being applied.
 	 * If the transaction is cancelled and rolled back, a corresponding change event will also be emitted for the rollback.
 	 */
-	runTransaction<TRoot>(
-		tree: TreeView<TRoot>,
-		transaction: (root: TRoot) => void | "rollback",
+	runTransaction<TView extends TreeView<ImplicitFieldSchema>>(
+		tree: TView,
+		transaction: (root: TView["root"]) => void | "rollback",
+		preconditions?: TransactionConstraint[],
 	): void;
+
+	/**
+	 * Check if the subtree defined by `node` contains `other`.
+	 *
+	 * @returns true if `other` is an inclusive descendant of `node`, and false otherwise.
+	 * @remarks
+	 * This includes direct and indirect children:
+	 * as long as `node` is an ancestor of `other` (occurs in its parentage chain), this returns true, regardless of the number of levels of the tree between.
+	 *
+	 * `node` is considered to contain itself, so the case where `node === other` returns true.
+	 *
+	 * This is handy when checking if moving `node` into `other` would create a cycle and thus is invalid.
+	 *
+	 * This check walks the parents of `other` looking for `node`,
+	 * and thus runs in time proportional to the depth of child in the tree.
+	 */
+	contains(node: TreeNode, other: TreeNode): boolean;
 }
 
 /**
@@ -64,13 +140,14 @@ export interface TreeApi extends TreeNodeApi {
  */
 export const treeApi: TreeApi = {
 	...treeNodeApi,
-	runTransaction<TNode extends TreeNode, TRoot>(
+	runTransaction<TNode extends TreeNode, TRoot extends ImplicitFieldSchema>(
 		treeOrNode: TNode | TreeView<TRoot>,
 		transaction: ((node: TNode) => void | "rollback") | ((root: TRoot) => void | "rollback"),
+		preconditions: TransactionConstraint[] = [],
 	) {
 		if (treeOrNode instanceof SchematizingSimpleTreeView) {
 			const t = transaction as (root: TRoot) => void | "rollback";
-			runTransaction(treeOrNode.checkout, () => t(treeOrNode.root as TRoot));
+			runTransaction(treeOrNode.checkout, () => t(treeOrNode.root as TRoot), preconditions);
 		} else {
 			const node = treeOrNode as TNode;
 			const t = transaction as (node: TNode) => void | "rollback";
@@ -80,13 +157,67 @@ export const treeApi: TreeApi = {
 				contextToTreeView.get(context) ??
 				fail("Expected view to be registered for context");
 
-			runTransaction(treeView.checkout, () => t(node));
+			runTransaction(treeView.checkout, () => t(node), preconditions);
+		}
+	},
+
+	contains(parent: TreeNode, child: TreeNode): boolean {
+		let toCheck: TreeNode | undefined = child;
+		while (toCheck !== undefined) {
+			if (toCheck === parent) {
+				return true;
+			}
+			toCheck = treeApi.parent(toCheck);
 		}
+		return false;
 	},
 };
 
-function runTransaction(checkout: TreeCheckout, transaction: () => void | "rollback"): void {
+/**
+ * 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 {
+	type: "nodeInDocument";
+	node: TreeNode;
+}
+
+// TODO: Add more constraint types here
+
+function runTransaction(
+	checkout: TreeCheckout,
+	transaction: () => void | "rollback",
+	preconditions: TransactionConstraint[],
+): void {
 	checkout.transaction.start();
+	for (const constraint of preconditions) {
+		switch (constraint.type) {
+			case "nodeInDocument": {
+				const node = getFlexNode(constraint.node);
+				assert(
+					node.treeStatus() === TreeStatus.InDocument,
+					0x90f /* Attempted to apply "nodeExists" constraint when building a transaction, but the node is not in the document. */,
+				);
+				checkout.editor.addNodeExistsConstraint(node.anchorNode);
+				break;
+			}
+			default:
+				unreachableCase(constraint.type);
+		}
+	}
 	let result: void | "rollback";
 	try {
 		result = transaction();

package/src/shared-tree/treeCheckout.ts

@@ -2,44 +2,52 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { assert } from "@fluidframework/core-utils";
+
+import { assert } from "@fluidframework/core-utils/internal";
 import { IIdCompressor } from "@fluidframework/id-compressor";
+
+import { noopValidator } from "../codec/index.js";
 import {
-	AnchorLocator,
-	IForestSubscription,
-	AnchorSetRootEvents,
 	Anchor,
+	AnchorLocator,
 	AnchorNode,
 	AnchorSet,
+	AnchorSetRootEvents,
+	ChangeFamily,
+	CommitKind,
+	CommitMetadata,
+	DeltaVisitor,
+	DetachedFieldIndex,
 	IEditableForest,
+	IForestSubscription,
+	JsonableTree,
+	Revertible,
+	RevertibleStatus,
+	RevisionTag,
+	RevisionTagCodec,
+	TreeStoredSchema,
 	TreeStoredSchemaRepository,
+	TreeStoredSchemaSubscription,
 	combineVisitors,
-	visitDelta,
-	DetachedFieldIndex,
 	makeDetachedFieldIndex,
-	Revertible,
-	ChangeFamily,
+	rebaseChange,
 	tagChange,
-	TreeStoredSchema,
-	TreeStoredSchemaSubscription,
-	JsonableTree,
-	RevisionTagCodec,
-	DeltaVisitor,
+	visitDelta,
 } from "../core/index.js";
 import { HasListeners, IEmitter, ISubscribable, createEmitter } from "../events/index.js";
 import {
+	FieldBatchCodec,
+	TreeCompressionStrategy,
 	buildForest,
 	intoDelta,
-	FieldBatchCodec,
 	jsonableTreeFromCursor,
 	makeFieldBatchCodec,
-	TreeCompressionStrategy,
 } from "../feature-libraries/index.js";
 import { SharedTreeBranch, getChangeReplaceType } from "../shared-tree-core/index.js";
-import { TransactionResult, fail } from "../util/index.js";
-import { noopValidator } from "../codec/index.js";
+import { IDisposable, TransactionResult, disposeSymbol, fail } from "../util/index.js";
+
+import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamily.js";
 import { SharedTreeChange } from "./sharedTreeChangeTypes.js";
-import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 
 /**
@@ -49,7 +57,7 @@ import { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilde
 export interface CheckoutEvents {
 	/**
 	 * A batch of changes has finished processing and the view is in a consistent state.
-	 * It is once again safe to access the EditableTree, Forest and AnchorSet.
+	 * It is once again safe to access the FlexTree, Forest and AnchorSet.
 	 *
 	 * @remarks
 	 * This is mainly useful for knowing when to do followup work scheduled during events from Anchors.
@@ -64,19 +72,28 @@ export interface CheckoutEvents {
 	 *
 	 * @param revertible - The revertible that can be used to revert the change.
 	 */
-	newRevertible(revertible: Revertible): void;
 
 	/**
-	 * Fired when a revertible is either reverted or discarded.
-	 *
-	 * This event can be used to maintain a list or set of active revertibles.
-	 * @param revertible - The revertible that was disposed.
-	 * This revertible was previously passed to the `newRevertible` event.
-	 * Calling `discard` on this revertible is not necessary but is safe to do.
+	 * {@inheritdoc TreeViewEvents.commitApplied}
 	 */
-	revertibleDisposed(revertible: Revertible): void;
+	commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
 }
 
+/**
+ * Factory for creating a {@link Revertible}.
+ * Will error if invoked outside the scope of the `commitApplied` event that provides it, or if invoked multiple times.
+ *
+ * @param onRevertibleDisposed - A callback that will be invoked when the `Revertible` generated by this factory is disposed.
+ * This happens when the `Revertible` is disposed manually, or when the `TreeView` that the `Revertible` belongs to is disposed,
+ * whichever happens first.
+ * This is typically used to clean up any resources associated with the `Revertible` in the host application.
+ *
+ * @public
+ */
+export type RevertibleFactory = (
+	onRevertibleDisposed?: (revertible: Revertible) => void,
+) => Revertible;
+
 /**
  * Provides a means for interacting with a SharedTree.
  * This includes reading data from the tree and running transactions to mutate the tree.
@@ -185,6 +202,7 @@ export interface ITreeCheckout extends AnchorLocator {
  */
 export function createTreeCheckout(
 	idCompressor: IIdCompressor,
+	mintRevisionTag: () => RevisionTag,
 	revisionTagCodec: RevisionTagCodec,
 	args?: {
 		branch?: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>;
@@ -202,11 +220,13 @@ export function createTreeCheckout(
 	const forest = args?.forest ?? buildForest();
 	const schema = args?.schema ?? new TreeStoredSchemaRepository();
 	const defaultCodecOptions = { jsonValidator: noopValidator };
+	const defaultFieldBatchVersion = 1;
 	const changeFamily =
 		args?.changeFamily ??
 		new SharedTreeChangeFamily(
 			revisionTagCodec,
-			args?.fieldBatchCodec ?? makeFieldBatchCodec(defaultCodecOptions),
+			args?.fieldBatchCodec ??
+				makeFieldBatchCodec(defaultCodecOptions, defaultFieldBatchVersion),
 			{ jsonValidator: noopValidator },
 			args?.chunkCompressionStrategy,
 		);
@@ -231,6 +251,7 @@ export function createTreeCheckout(
 		schema,
 		forest,
 		events,
+		mintRevisionTag,
 		revisionTagCodec,
 		args?.removedRoots,
 	);
@@ -311,7 +332,7 @@ class Transaction implements ITransaction {
  * {@link ITreeCheckout} that has forked off of the main trunk/branch.
  * @internal
  */
-export interface ITreeCheckoutFork extends ITreeCheckout {
+export interface ITreeCheckoutFork extends ITreeCheckout, IDisposable {
 	/**
 	 * Rebase the changes that have been applied to this view over all the new changes in the given view.
 	 * @param view - Either the root view or a view that was created by a call to `fork()`. It is not modified by this operation.
@@ -323,6 +344,23 @@ export interface ITreeCheckoutFork extends ITreeCheckout {
  * An implementation of {@link ITreeCheckoutFork}.
  */
 export class TreeCheckout implements ITreeCheckoutFork {
+	private isDisposed = false;
+
+	/**
+	 * Set of revertibles maintained for automatic disposal
+	 */
+	private readonly revertibles = new Set<DisposableRevertible>();
+
+	/**
+	 * Each branch's head commit corresponds to a revertible commit.
+	 * Maintaining a whole branch ensures the commit graph is not pruned in a way that would prevent the commit from
+	 * being reverted.
+	 */
+	private readonly revertibleCommitBranches = new Map<
+		RevisionTag,
+		SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>
+	>();
+
 	public constructor(
 		public readonly transaction: ITransaction,
 		private readonly branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,
@@ -332,6 +370,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		public readonly events: ISubscribable<CheckoutEvents> &
 			IEmitter<CheckoutEvents> &
 			HasListeners<CheckoutEvents>,
+		private readonly mintRevisionTag: () => RevisionTag,
 		private readonly revisionTagCodec: RevisionTagCodec,
 		private readonly removedRoots: DetachedFieldIndex = makeDetachedFieldIndex(
 			"repair",
@@ -354,14 +393,21 @@ export class TreeCheckout implements ITreeCheckoutFork {
 							visitDelta(delta, visitor, this.removedRoots);
 						});
 					} else if (change.type === "schema") {
-						// We purge all removed content because the schema change may render that repair data invalid.
-						// This happens on all peers that receive the schema change.
-						// Note that while the originator of the schema change could theoretically validate/update the
-						// repair data that it has, so that is it guaranteed to be valid with the new schema, we cannot
-						// guarantee that the originator has a superset of the repair data that other clients have.
-						// This means the originator cannot guarantee that the repair data on all peers is valid for
-						// the new schema.
-						this.purgeRemovedRoots();
+						// Schema changes from a current to a new schema are expected to be backwards compatible.
+						// This guarantees that all data in the forest (which is valid before the schema change)
+						// is also valid under the new schema.
+						// Note however, that such schema changes may in some cases be rolled back:
+						// Case 1: A transaction with a schema change may be aborted.
+						// The transaction may have made some data changes that would render some trees invalid
+						// under the old schema, but these changes will also be rolled back, thereby putting the forest
+						// back in the state before the transaction, which is valid under the original (reinstated) schema.
+						// Case 2: A branch with a schema change may be rebased such that the schema change (because
+						// of a constraint) is no longer applied.
+						// Such a branch may contain data changes that would render some trees invalid under the
+						// original schema. These data changes may not necessarily be rolled back.
+						// They will however be rebased over the rollback of the schema change. This rebasing will
+						// ensure that these data changes are muted if they would render some trees invalid under the
+						// original (reinstated) schema.
 						storedSchema.apply(change.innerChange.schema.new);
 					} else {
 						fail("Unknown Shared Tree change type.");
@@ -376,12 +422,59 @@ export class TreeCheckout implements ITreeCheckoutFork {
 				}
 			}
 		});
-		branch.on("newRevertible", (revertible) => {
-			this.events.emit("newRevertible", revertible);
-		});
-		branch.on("revertibleDisposed", (revertible, revision) => {
-			// We do not expose the revision in this API
-			this.events.emit("revertibleDisposed", revertible);
+		branch.on("commitApplied", (data) => {
+			const commit = branch.getHead();
+			const { change, revision } = commit;
+			let withinEventContext = true;
+
+			const getRevertible = hasSchemaChange(change)
+				? undefined
+				: (onRevertibleDisposed?: (revertible: Revertible) => void) => {
+						assert(
+							withinEventContext,
+							0x902 /* cannot get a revertible outside of the context of a commitApplied event */,
+						);
+						assert(
+							this.revertibleCommitBranches.get(revision) === undefined,
+							0x903 /* cannot get the revertible more than once */,
+						);
+
+						const revertibleCommits = this.revertibleCommitBranches;
+						const revertible: DisposableRevertible = {
+							get status(): RevertibleStatus {
+								const revertibleCommit = revertibleCommits.get(revision);
+								return revertibleCommit === undefined
+									? RevertibleStatus.Disposed
+									: RevertibleStatus.Valid;
+							},
+							revert: (release: boolean = true) => {
+								assert(
+									revertible.status === RevertibleStatus.Valid,
+									0x904 /* a disposed revertible cannot be reverted */,
+								);
+								this.revertRevertible(revision, data.kind);
+								if (release) {
+									revertible[disposeSymbol]();
+								}
+							},
+							[disposeSymbol]: () => revertible.dispose(),
+							dispose: () => {
+								assert(
+									revertible.status === RevertibleStatus.Valid,
+									0x910 /* a disposed revertible cannot be disposed */,
+								);
+								this.disposeRevertible(revertible, revision);
+								onRevertibleDisposed?.(revertible);
+							},
+						};
+
+						this.revertibleCommitBranches.set(revision, branch.fork());
+						this.revertibles.add(revertible);
+						return revertible;
+				  };
+
+			this.events.emit("commitApplied", data, getRevertible);
+			withinEventContext = false;
 		});
 	}
 
@@ -395,17 +488,8 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		combinedVisitor.free();
 	}
 
-	private purgeRemovedRoots() {
-		// Revertibles are susceptible to use repair data so we purge them.
-		this.branch.purgeRevertibles();
-		this.withCombinedVisitor((visitor) => {
-			for (const { root } of this.removedRoots.entries()) {
-				const field = this.removedRoots.toFieldKey(root);
-				// TODO:AD5509 Handle arbitrary-length fields once the storage of removed roots is no longer atomized.
-				visitor.destroy(field, 1);
-			}
-		});
-		this.removedRoots.purge();
+	private checkNotDisposed(): void {
+		assert(!this.isDisposed, 0x911 /* Invalid operation on a disposed TreeCheckout */);
 	}
 
 	public get rootEvents(): ISubscribable<AnchorSetRootEvents> {
@@ -413,14 +497,17 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	}
 
 	public get editor(): ISharedTreeEditor {
+		this.checkNotDisposed();
 		return this.branch.editor;
 	}
 
 	public locate(anchor: Anchor): AnchorNode | undefined {
+		this.checkNotDisposed();
 		return this.forest.anchors.locate(anchor);
 	}
 
 	public fork(): TreeCheckout {
+		this.checkNotDisposed();
 		const anchors = new AnchorSet();
 		const branch = this.branch.fork();
 		const storedSchema = this.storedSchema.clone();
@@ -433,22 +520,26 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			storedSchema,
 			forest,
 			createEmitter(),
+			this.mintRevisionTag,
 			this.revisionTagCodec,
 			this.removedRoots.clone(),
 		);
 	}
 
 	public rebase(view: TreeCheckout): void {
+		this.checkNotDisposed();
 		view.branch.rebaseOnto(this.branch);
 	}
 
 	public rebaseOnto(view: ITreeCheckout): void {
+		this.checkNotDisposed();
 		view.rebase(this);
 	}
 
 	public merge(view: TreeCheckout): void;
 	public merge(view: TreeCheckout, disposeView: boolean): void;
 	public merge(view: TreeCheckout, disposeView = true): void {
+		this.checkNotDisposed();
 		assert(
 			!this.transaction.inProgress() || disposeView,
 			0x710 /* A view that is merged into an in-progress transaction must be disposed */,
@@ -458,19 +549,19 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		}
 		this.branch.merge(view.branch);
 		if (disposeView) {
-			view.dispose();
+			view[disposeSymbol]();
 		}
 	}
 
 	public updateSchema(newSchema: TreeStoredSchema): void {
+		this.checkNotDisposed();
 		this.editor.schema.setStoredSchema(this.storedSchema.clone(), newSchema);
 	}
 
-	/**
-	 * Dispose this view, freezing its state and allowing the SharedTree to release resources required by it.
-	 * Attempts to further mutate or dispose this view will error.
-	 */
-	public dispose(): void {
+	public [disposeSymbol](): void {
+		this.checkNotDisposed();
+		this.isDisposed = true;
+		this.purgeRevertibles();
 		this.branch.dispose();
 	}
 
@@ -495,6 +586,54 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		cursor.free();
 		return trees;
 	}
+
+	private purgeRevertibles(): void {
+		for (const revertible of this.revertibles) {
+			revertible.dispose();
+		}
+	}
+
+	private disposeRevertible(revertible: DisposableRevertible, revision: RevisionTag): void {
+		this.revertibleCommitBranches.get(revision)?.dispose();
+		this.revertibleCommitBranches.delete(revision);
+		this.revertibles.delete(revertible);
+	}
+
+	private revertRevertible(revision: RevisionTag, kind: CommitKind): void {
+		assert(
+			!this.branch.isTransacting(),
+			0x7cb /* Undo is not yet supported during transactions */,
+		);
+
+		const revertibleBranch = this.revertibleCommitBranches.get(revision);
+		assert(revertibleBranch !== undefined, 0x7cc /* expected to find a revertible commit */);
+		const commitToRevert = revertibleBranch.getHead();
+
+		let change = this.changeFamily.rebaser.invert(
+			tagChange(commitToRevert.change, revision),
+			false,
+		);
+
+		const headCommit = this.branch.getHead();
+		// Rebase the inverted change onto any commits that occurred after the undoable commits.
+		if (commitToRevert !== headCommit) {
+			change = rebaseChange(
+				this.changeFamily.rebaser,
+				change,
+				commitToRevert,
+				headCommit,
+				this.mintRevisionTag,
+			);
+		}
+
+		this.branch.apply(
+			change,
+			this.mintRevisionTag(),
+			kind === CommitKind.Default || kind === CommitKind.Redo
+				? CommitKind.Undo
+				: CommitKind.Redo,
+		);
+	}
 }
 
 /**
@@ -516,3 +655,7 @@ export function runSynchronous(
 		? view.transaction.abort()
 		: view.transaction.commit();
 }
+
+interface DisposableRevertible extends Revertible {
+	dispose: () => void;
+}

package/src/shared-tree/treeView.ts

@@ -5,16 +5,17 @@
 
 import { FieldKey } from "../core/index.js";
 import {
+	Context,
 	FlexFieldSchema,
+	FlexTreeContext,
 	FlexTreeSchema,
 	FlexTreeTypedField,
-	FlexTreeContext,
 	NodeKeyManager,
 	getTreeContext,
-	Context,
 } from "../feature-libraries/index.js";
 import { IDisposable, disposeSymbol } from "../util/index.js";
-import { ITreeCheckoutFork, ITreeCheckout, TreeCheckout } from "./treeCheckout.js";
+
+import { ITreeCheckout, ITreeCheckoutFork, TreeCheckout } from "./treeCheckout.js";
 
 /**
  * An editable view of a (version control style) branch of a shared tree.
@@ -26,7 +27,7 @@ import { ITreeCheckoutFork, ITreeCheckout, TreeCheckout } from "./treeCheckout.j
  */
 export interface FlexTreeView<in out TRoot extends FlexFieldSchema> extends IDisposable {
 	/**
-	 * Context for controlling the EditableTree nodes produced from {@link FlexTreeView.flexTree}.
+	 * Context for controlling the FlexTree nodes produced from {@link FlexTreeView.flexTree}.
 	 *
 	 * @remarks
 	 * This is an owning reference: disposing of this view disposes its context.