@fluidframework/tree 2.116.1 → 2.117.0

package/src/shared-tree/sharedTree.ts

@@ -524,6 +524,7 @@ export const changeFormatVersionForEditManager = DependentFormatVersion.fromPair
 	[EditManagerFormatVersion.v4, SharedTreeChangeFormatVersion.v4],
 	[EditManagerFormatVersion.vSharedBranches, SharedTreeChangeFormatVersion.v4],
 	[EditManagerFormatVersion.v6, SharedTreeChangeFormatVersion.v5],
+	[EditManagerFormatVersion.v7, SharedTreeChangeFormatVersion.v5],
 ]);
 
 /**
@@ -540,6 +541,7 @@ export const changeFormatVersionForMessage = DependentFormatVersion.fromPairs<
 	[MessageFormatVersion.v4, SharedTreeChangeFormatVersion.v4],
 	[MessageFormatVersion.vSharedBranches, SharedTreeChangeFormatVersion.v4],
 	[MessageFormatVersion.v6, SharedTreeChangeFormatVersion.v5],
+	[MessageFormatVersion.v7, SharedTreeChangeFormatVersion.v5],
 ]);
 
 function getCodecTreeForEditManagerFormat(
@@ -659,8 +661,9 @@ export interface SharedTreeOptions
 	 * @remarks
 	 * By default, SharedTree evicts trunk commits once all peers have acknowledged them (i.e. once they
 	 * are outside the collaboration window), and they are not otherwise retained (e.g. by revertibles or
-	 * local branches), to bound memory usage. Enabling this flag retains the full trunk history for the
-	 * lifetime of the client, which increases memory usage over time and should be used with care.
+	 * local branches), to bound memory usage and document size.
+	 * As long as this flag is enabled, trunk commits are retained - this increases memory usage and document size
+	 * over time and should be used with care.
 	 */
 	readonly retainHistory?: boolean;
 

package/src/shared-tree/tree.ts

@@ -58,7 +58,7 @@ export const Tree: Tree = {
 	...treeNodeApi,
 
 	// Note: the implementation details of `createRunTransaction` are deprecated.
-	// We have introduced replacement `@alpha` APIs on `TreeBranch`, but until they are `@public`, we can't reasonably deprecated this.
+	// We have introduced replacement `@alpha` APIs on `UntypedTreeView`, but until they are `@public`, we can't reasonably deprecated this.
 	// Once they have been promoted to public, we can deprecate this API.
 	runTransaction: createRunTransaction(),
 

package/src/shared-tree/treeAlpha.ts

@@ -58,7 +58,7 @@ import {
 	type TreeEncodingOptions,
 	type VerboseTree,
 	extractPersistedSchema,
-	type TreeBranch,
+	type UntypedTreeView,
 	TreeViewConfigurationAlpha,
 	getStoredKey,
 	getPropertyKeyFromStoredKey,
@@ -84,7 +84,6 @@ import {
 	type TreeContextAlpha,
 	type TreeNodeSchema,
 	getUnhydratedContext,
-	type TreeBranchAlpha,
 } from "../simple-tree/index.js";
 import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 
@@ -96,22 +95,22 @@ const identifier: TreeIdentifierUtils = (node: TreeNode): string | undefined =>
 	return getIdentifierFromNode(node, "uncompressed");
 };
 
-identifier.shorten = (branch: TreeBranch, nodeIdentifier: string): number | undefined => {
+identifier.shorten = (view: UntypedTreeView, nodeIdentifier: string): number | undefined => {
 	assert(
-		branch instanceof SchematizingSimpleTreeView,
+		view instanceof SchematizingSimpleTreeView,
 		0xcac /* Unexpected branch implementation */,
 	);
-	const { nodeKeyManager } = branch;
+	const { nodeKeyManager } = view;
 	const localNodeKey = nodeKeyManager.tryLocalizeNodeIdentifier(nodeIdentifier);
 	return localNodeKey === undefined ? undefined : extractFromOpaque(localNodeKey);
 };
 
-identifier.lengthen = (branch: TreeBranch, nodeIdentifier: number): string => {
+identifier.lengthen = (view: UntypedTreeView, nodeIdentifier: number): string => {
 	assert(
-		branch instanceof SchematizingSimpleTreeView,
+		view instanceof SchematizingSimpleTreeView,
 		0xcad /* Unexpected branch implementation */,
 	);
-	const { nodeKeyManager } = branch;
+	const { nodeKeyManager } = view;
 	const local = brand<LocalNodeIdentifier>(nodeIdentifier as SessionSpaceCompressedId);
 	return nodeKeyManager.stabilizeNodeIdentifier(local);
 };
@@ -121,8 +120,8 @@ identifier.getShort = (node: TreeNode): number | undefined => {
 	return typeof shortIdentifier === "number" ? shortIdentifier : undefined;
 };
 
-identifier.create = (branch: TreeBranch): string => {
-	const nodeKeyManager = (branch as SchematizingSimpleTreeView<ImplicitFieldSchema>)
+identifier.create = (view: UntypedTreeView): string => {
+	const nodeKeyManager = (view as SchematizingSimpleTreeView<ImplicitFieldSchema>)
 		.nodeKeyManager;
 	return nodeKeyManager.stabilizeNodeIdentifier(nodeKeyManager.generateLocalNodeIdentifier());
 };
@@ -154,7 +153,7 @@ export interface TreeIdentifierUtils {
 	(node: TreeNode): string | undefined;
 
 	/**
-	 * Returns the shortened identifier as a number given a UUID known by the id compressor on the branch.
+	 * Returns the shortened identifier as a number given a UUID known by the id compressor on the view.
 	 * @remarks
 	 * If the given string is not a valid identifier and/or was not generated by the SharedTree, this will return `undefined`.
 	 *
@@ -163,10 +162,10 @@ export interface TreeIdentifierUtils {
 	 * This method is the inverse of {@link TreeIdentifierUtils.lengthen}.
 	 * If you shorten an identifier and then immediately pass it to {@link TreeIdentifierUtils.lengthen}, you will get the original string back.
 	 *
-	 * @param branch - The branch (and/or view) of the SharedTree that will perform the compression.
+	 * @param view - The view of the SharedTree that will perform the compression.
 	 * @param nodeIdentifier - the stable identifier to be shortened.
 	 */
-	shorten(branch: TreeBranch, nodeIdentifier: string): number | undefined;
+	shorten(view: UntypedTreeView, nodeIdentifier: string): number | undefined;
 
 	/**
 	 * Returns the stable id as a string if the identifier is decompressible and known by the id compressor.
@@ -176,10 +175,10 @@ export interface TreeIdentifierUtils {
 	 * This method is the inverse of {@link TreeIdentifierUtils.shorten}.
 	 * If you lengthen an identifier and then immediately pass it to {@link TreeIdentifierUtils.shorten}, you will get the original short identifier back.
 	 *
-	 * @param branch - The branch (and/or view) of the SharedTree that will perform the decompression.
+	 * @param view - The view of the SharedTree that will perform the decompression.
 	 * @param nodeIdentifier - The local identifier to be lengthened.
 	 */
-	lengthen(branch: TreeBranch, nodeIdentifier: number): string;
+	lengthen(view: UntypedTreeView, nodeIdentifier: number): string;
 
 	/**
 	 * Returns the {@link TreeIdentifierUtils.shorten | shortened} form of the identifier {@link SchemaFactory.identifier | identifier} for the given node.
@@ -206,9 +205,9 @@ export interface TreeIdentifierUtils {
 	 * @remarks
 	 * The returned UUID string can be {@link TreeIdentifierUtils.shorten | shortened} for high-performance scenarios.
 	 *
-	 * @param branch - The branch (and/or view) of the SharedTree that will generate and manage the identifier.
+	 * @param view - The view of the SharedTree that will generate and manage the identifier.
 	 */
-	create(branch: TreeBranch): string;
+	create(view: UntypedTreeView): string;
 }
 
 /**
@@ -253,19 +252,6 @@ export interface TreeAlpha {
 		listener: NoInfer<TreeChangeEventsAlpha<TNode>[K]>,
 	): () => void;
 
-	/**
-	 * Retrieve the {@link TreeBranch | branch}, if any, for the given node.
-	 * @param node - The node to query
-	 * @remarks If the node has already been inserted into the tree, this will return the branch associated with that node's {@link TreeView | view}.
-	 * Otherwise, it will return `undefined` (because the node has not yet been inserted and is therefore not part of a branch or view).
-	 *
-	 * This does not fork a new branch, but rather retrieves the _existing_ branch for the node.
-	 * To create a new branch, use e.g. {@link TreeBranch.fork | `myBranch.fork()`}.
-	 *
-	 * @deprecated To obtain a {@link TreeBranchAlpha | branch }, use `TreeAlpha.context(node)` to obtain a {@link TreeContextAlpha | context} and then check {@link TreeContextAlpha.isBranch | isBranch()}.
-	 */
-	branch(node: TreeNode): TreeBranchAlpha | undefined;
-
 	/**
 	 * Retrieve the {@link TreeContextAlpha | context} for the given node.
 	 * @param node - The node to query
@@ -842,13 +828,9 @@ export const TreeAlpha: TreeAlpha = {
 	},
 
 	context(node: TreeNode): TreeContextAlpha {
-		return this.branch(node) ?? UnhydratedTreeContext.instance;
-	},
-
-	branch(node: TreeNode): TreeBranchAlpha | undefined {
 		const kernel = getKernel(node);
 		if (!kernel.isHydrated()) {
-			return undefined;
+			return UnhydratedTreeContext.instance;
 		}
 		const view = kernel.anchorNode.anchorSet.slots.get(ViewSlot);
 		assert(

package/src/shared-tree/treeCheckout.ts

@@ -10,7 +10,7 @@ import type {
 	Listenable,
 } from "@fluidframework/core-interfaces/internal";
 import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
+import type { IIdCompressor, StableId } from "@fluidframework/id-compressor";
 import { type TelemetryLoggerExt, UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -45,6 +45,9 @@ import {
 	visitDelta,
 	type RevertibleAlphaFactory,
 	type RevertibleAlpha,
+	type RevertOptionsAlpha,
+	type RevertToOptionsAlpha,
+	type CustomMetadataTree,
 	type GraphCommit,
 	isAncestor,
 	moveToDetachedField,
@@ -63,6 +66,7 @@ import {
 	findCommonAncestor,
 	rebaseBranch,
 	type LocalCommitEvents,
+	findAncestor,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -91,8 +95,8 @@ import {
 	type TreeViewConfiguration,
 	type UnsafeUnknownSchema,
 	type ViewableTree,
-	type TreeBranch,
-	type TreeBranchAlpha,
+	type UntypedTreeView,
+	type UntypedTreeViewAlpha,
 	type VerboseTree,
 	type VoidTransactionCallbackStatusAlpha,
 	type TransactionCallbackStatusAlpha,
@@ -115,10 +119,12 @@ import {
 	hasSome,
 	throwIfBroken,
 	type JsonCompatibleReadOnly,
+	type JsonCompatibleReadOnlyObject,
 	type WithBreakable,
 } from "../util/index.js";
 
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+import { DefaultTreeBranchHistory } from "./history.js";
 import { SharedTreeChangeEnricher } from "./sharedTreeChangeEnricher.js";
 import type { SharedTreeChangeProcessingContext } from "./sharedTreeChangeFamily.js";
 import {
@@ -132,6 +138,46 @@ import type { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditB
 import { extractTransactionChangeProcessor } from "./transactionPostProcessor.js";
 import { SerializedChange } from "./serializedChange.js";
 
+/**
+ * Returns a defensive copy of the given metadata, validating that it can be persisted.
+ * @remarks
+ * The round-trip through JSON ensures that the value read back locally is exactly the value that peers and
+ * future summaries will see, and that later mutation of the caller's object cannot affect an existing commit.
+ * @throws A `UsageError` if the value cannot be represented as a JSON object.
+ */
+function snapshotCustomMetadata(
+	customMetadata: JsonCompatibleReadOnlyObject | undefined,
+): JsonCompatibleReadOnlyObject | undefined {
+	if (customMetadata === undefined) {
+		return undefined;
+	}
+	let serialized: string | undefined;
+	try {
+		serialized = JSON.stringify(customMetadata);
+	} catch (error: unknown) {
+		throw new UsageError(
+			`"customMetadata" must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	if (serialized === undefined) {
+		throw new UsageError(`"customMetadata" must be JSON-serializable.`);
+	}
+	const snapshot: unknown = JSON.parse(serialized);
+	if (typeof snapshot !== "object" || snapshot === null || Array.isArray(snapshot)) {
+		throw new UsageError(`"customMetadata" must be a JSON object.`);
+	}
+	return snapshot as JsonCompatibleReadOnlyObject;
+}
+
+/**
+ * Wraps metadata for an operation which produces a single commit.
+ */
+function toMetadataTree(
+	customMetadata: JsonCompatibleReadOnlyObject | undefined,
+): CustomMetadataTree | undefined {
+	return customMetadata === undefined ? undefined : { metadata: customMetadata, children: [] };
+}
+
 /**
  * Yields all defined (non-`undefined`) labels from a {@link LabelTree}, depth-first.
  */
@@ -235,7 +281,7 @@ export type TreeTransactor = Transactor<
  * Implementations of this interface must implement the {@link branchKey} property.
  */
 export interface ITreeCheckout
-	extends TreeBranchAlpha,
+	extends UntypedTreeViewAlpha,
 		AnchorLocator,
 		ViewableTree,
 		WithBreakable {
@@ -362,6 +408,7 @@ export function createTreeCheckout(
 			{
 				change: changeFamily.rebaser.compose([]),
 				revision: "root",
+				customMetadata: undefined,
 			},
 			changeFamily,
 			() => idCompressor.generateCompressedId(),
@@ -395,9 +442,9 @@ export interface RevertMetrics {
 }
 
 /**
- * Get the {@link TreeCheckout} associated with a given {@link TreeBranch}.
+ * Get the {@link TreeCheckout} associated with a given {@link UntypedTreeView}.
  */
-function getCheckout(context: TreeBranch): TreeCheckout {
+function getCheckout(context: UntypedTreeView): TreeCheckout {
 	if (context instanceof TreeCheckout) {
 		return context;
 	}
@@ -566,9 +613,10 @@ export class TreeCheckout implements ITreeCheckout {
 
 	readonly #events = createEmitter<CheckoutEvents>();
 	public events: Listenable<CheckoutEvents> = this.#events;
+	private _branchHistory?: DefaultTreeBranchHistory;
 
 	public constructor(
-		branch: SharedTreeBranch<
+		private branch: SharedTreeBranch<
 			SharedTreeEditBuilder,
 			SharedTreeChange,
 			SharedTreeChangeProcessingContext
@@ -593,6 +641,11 @@ export class TreeCheckout implements ITreeCheckout {
 		this.registerForBranchEvents();
 	}
 
+	public get branchHistory(): DefaultTreeBranchHistory {
+		this._branchHistory ??= new DefaultTreeBranchHistory(this.branch, this.idCompressor);
+		return this._branchHistory;
+	}
+
 	/**
 	 * Pushes a new label node for a transaction nesting level.
 	 *
@@ -962,17 +1015,21 @@ export class TreeCheckout implements ITreeCheckout {
 			serializedChange,
 		);
 		// Apply the change to the branch, but _not_ the `activeBranch` - we do not support squashing serialized commits in a transaction.
-		this.#transaction.branch.apply(change);
+		this.#transaction.branch.apply(change, CommitKind.Default, undefined);
 	}
 
-	// #region TreeBranchAlpha
+	// #region UntypedTreeViewAlpha
 
 	@throwIfBroken
 	public applyChange(change: JsonCompatibleReadOnly): void {
 		this.applySerializedChange(change);
 	}
 
-	public isBranch(): this is TreeBranchAlpha {
+	public isBranch(): this is UntypedTreeViewAlpha {
+		return this.isView();
+	}
+
+	public isView(): this is UntypedTreeViewAlpha {
 		return true;
 	}
 
@@ -1047,6 +1104,9 @@ export class TreeCheckout implements ITreeCheckout {
 		this.pushLabelFrame(params?.label);
 		this.transaction.start({
 			postProcessor: extractTransactionChangeProcessor(params?.postProcessor),
+			// Like the validation described above, rejecting malformed metadata breaks the checkout rather
+			// than being recoverable. Tracked by https://github.com/microsoft/FluidFramework/issues/28085.
+			customMetadata: snapshotCustomMetadata(params?.customMetadata),
 		});
 
 		addConstraintsToTransaction(this, false, params?.preconditions);
@@ -1084,7 +1144,7 @@ export class TreeCheckout implements ITreeCheckout {
 			: { success: true, value: value as TSuccessValue };
 	}
 
-	// #endregion TreeBranchAlpha
+	// #endregion UntypedTreeViewAlpha
 
 	// Revision is the revision of the commit, if any, which caused this change.
 	private applyInternalChange(change: SharedTreeChange, revision?: RevisionTag): void {
@@ -1182,24 +1242,33 @@ export class TreeCheckout implements ITreeCheckout {
 					? RevertibleStatus.Disposed
 					: RevertibleStatus.Valid;
 			},
-			revert: (release: boolean = true) => {
+			revert: (releaseOrOptions: boolean | RevertOptionsAlpha = true) => {
 				if (revertible.status === RevertibleStatus.Disposed) {
 					throw new UsageError("Unable to revert a revertible that has been disposed.");
 				}
 
-				const revertMetrics = checkout.revertRevertible(revision, kind, labelTree);
+				const options =
+					typeof releaseOrOptions === "boolean"
+						? { dispose: releaseOrOptions }
+						: releaseOrOptions;
+				const revertMetrics = checkout.revertRevertible(
+					revision,
+					kind,
+					labelTree,
+					snapshotCustomMetadata(options.customMetadata),
+				);
 				checkout.logger?.sendTelemetryEvent({
 					eventName: TreeCheckout.revertTelemetryEventName,
 					...revertMetrics,
 				});
 
-				if (release) {
+				if (options.dispose ?? true) {
 					revertible.dispose();
 				}
 			},
-			clone: (targetBranch: TreeBranch) => {
+			clone: (targetView: UntypedTreeView) => {
 				// 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 targetCheckout = getCheckout(targetBranch);
+				const targetCheckout = getCheckout(targetView);
 
 				const revertibleBranch = this.revertibleCommitBranches.get(revision);
 				if (revertibleBranch === undefined) {
@@ -1334,11 +1403,15 @@ export class TreeCheckout implements ITreeCheckout {
 			SharedTreeChangeProcessingContext
 		>,
 	): void {
-		// TODO: Dispose old branch, if necessary
 		assert(
 			this.#transaction.size === 0,
 			0xc55 /* Cannot switch branches during a transaction */,
 		);
+		if (this.isSharedBranch) {
+			throw new UsageError(
+				"Cannot switch a view away from a shared branch. Consider forking first.",
+			);
+		}
 		const diff = diffHistories(
 			this.changeFamily.rebaser,
 			this.#transaction.branch.getHead(),
@@ -1349,6 +1422,9 @@ export class TreeCheckout implements ITreeCheckout {
 		this.unregisterFromBranchEvents();
 
 		this.#transaction = this.createTransactionStack(branch);
+		this.branch = branch;
+		this._branchHistory?.dispose();
+		this._branchHistory = undefined;
 		this.editLock = new EditLock(this.#transaction.activeBranchEditor);
 		this.registerForBranchEvents();
 
@@ -1357,8 +1433,67 @@ export class TreeCheckout implements ITreeCheckout {
 		this.#events.emit("afterBatch");
 	}
 
-	private rebase(branch: TreeBranch): void {
-		const checkout = getCheckout(branch);
+	public rewindTo(revisionString: string): void {
+		this.checkNotDisposed("The branch has already been disposed and cannot be rewound.");
+		if (this.#transaction.size > 0) {
+			throw new UsageError("Rewinding is not supported during transactions.");
+		}
+		const revision = this.idCompressor.tryRecompress(revisionString as StableId);
+		if (revision === undefined) {
+			throw new UsageError(`Unrecognized revision id: ${revisionString}`);
+		}
+		const targetCommit = findAncestor(
+			this.#transaction.branch.getHead(),
+			(commit) => commit.revision === revision,
+		);
+		if (targetCommit === undefined) {
+			throw new UsageError(`No commit found with revision: ${revisionString}`);
+		}
+		this.switchBranch(this.#transaction.branch.fork(targetCommit));
+	}
+
+	public revertTo(revisionString: string, options?: RevertToOptionsAlpha): void {
+		this.checkNotDisposed(
+			"The branch has already been disposed and prior revisions cannot be reverted to.",
+		);
+		this.editLock.checkUnlocked("Reverting to a revision");
+		if (this.#transaction.size > 0) {
+			throw new UsageError("Reverting to a revision is not supported during transactions.");
+		}
+		const customMetadata = snapshotCustomMetadata(options?.customMetadata);
+		const revision = this.idCompressor.tryRecompress(revisionString as StableId);
+		if (revision === undefined) {
+			throw new UsageError(`Unrecognized revision id: ${revisionString}`);
+		}
+		// Populated with the commits that came after the target commit, from oldest to newest.
+		const commitsToUndo: GraphCommit<SharedTreeChange>[] = [];
+		const targetCommit = findAncestor(
+			[this.#transaction.activeBranch.getHead(), commitsToUndo],
+			(commit) => commit.revision === revision,
+		);
+		if (targetCommit === undefined) {
+			throw new UsageError(`No commit found with revision: ${revisionString}`);
+		}
+		if (!hasSome(commitsToUndo)) {
+			// The target commit is already the head of the branch, so there is nothing to revert.
+			return;
+		}
+		const revisionForInvert = this.mintRevisionTag();
+		const toUndo = this.changeFamily.rebaser.compose(commitsToUndo);
+		const inverse = this.changeFamily.rebaser.invert(
+			makeAnonChange(toUndo),
+			false,
+			revisionForInvert,
+		);
+		this.#transaction.branch.apply(
+			tagChange(inverse, revisionForInvert),
+			CommitKind.Default,
+			toMetadataTree(customMetadata),
+		);
+	}
+
+	private rebase(view: UntypedTreeView): void {
+		const checkout = getCheckout(view);
 		this.checkNotDisposed(
 			"The target branch of the rebase has been disposed and cannot be rebased.",
 		);
@@ -1384,15 +1519,15 @@ export class TreeCheckout implements ITreeCheckout {
 		checkout.#transaction.branch.rebaseOnto(this.#transaction.branch);
 	}
 
-	public rebaseOnto(branch: TreeBranch): void {
-		getCheckout(branch).rebase(this);
+	public rebaseOnto(view: UntypedTreeView): void {
+		getCheckout(view).rebase(this);
 	}
 
-	public isMissingEditsFrom(branch: TreeBranch): boolean {
-		const branchCheckout = getCheckout(branch);
+	public isMissingEditsFrom(view: UntypedTreeView): boolean {
+		const viewCheckout = getCheckout(view);
 		const targetPath: GraphCommit<unknown>[] = [];
 		const ancestor = findCommonAncestor(this.mainBranch.getHead(), [
-			branchCheckout.mainBranch.getHead(),
+			viewCheckout.mainBranch.getHead(),
 			targetPath,
 		]);
 		if (ancestor === undefined) {
@@ -1402,14 +1537,14 @@ export class TreeCheckout implements ITreeCheckout {
 	}
 
 	public computeNetChangeIfRebasedOnto(
-		branch: TreeBranch,
+		view: UntypedTreeView,
 	): JsonCompatibleReadOnly | undefined {
-		const branchCheckout = getCheckout(branch);
+		const viewCheckout = getCheckout(view);
 		const rebased = rebaseBranch(
 			this.mintRevisionTag,
 			this.changeFamily.rebaser,
 			this.#transaction.branch.getHead(),
-			branchCheckout.#transaction.branch.getHead(),
+			viewCheckout.#transaction.branch.getHead(),
 		);
 
 		if (rebased.sourceChange === undefined) {
@@ -1425,10 +1560,10 @@ export class TreeCheckout implements ITreeCheckout {
 		);
 	}
 
-	public merge(branch: TreeBranch): void;
-	public merge(branch: TreeBranch, disposeMerged: boolean): void;
-	public merge(branch: TreeBranch, disposeMerged = true): void {
-		const checkout = getCheckout(branch);
+	public merge(view: UntypedTreeView): void;
+	public merge(view: UntypedTreeView, disposeMerged: boolean): void;
+	public merge(view: UntypedTreeView, disposeMerged = true): void {
+		const checkout = getCheckout(view);
 		this.checkNotDisposed(
 			"The target branch of the merge has been disposed and cannot be merged.",
 		);
@@ -1481,6 +1616,8 @@ export class TreeCheckout implements ITreeCheckout {
 			view.dispose();
 		}
 		this.#events.emit("dispose");
+		this._branchHistory?.dispose();
+		this._branchHistory = undefined;
 	}
 
 	public getRemovedRoots(): [string | number | undefined, number, JsonableTree][] {
@@ -1529,6 +1666,7 @@ export class TreeCheckout implements ITreeCheckout {
 		revision: RevisionTag,
 		kind: CommitKind,
 		labelTree: LabelTree | undefined,
+		customMetadata: JsonCompatibleReadOnlyObject | undefined,
 	): RevertMetrics {
 		this.editLock.checkUnlocked("Reverting a commit");
 		if (this.transaction.size > 0) {
@@ -1583,6 +1721,7 @@ export class TreeCheckout implements ITreeCheckout {
 				kind === CommitKind.Default || kind === CommitKind.Redo
 					? CommitKind.Undo
 					: CommitKind.Redo,
+				toMetadataTree(customMetadata),
 			);
 		} finally {
 			this.labelTreeNode = previousLabelTreeNode;

package/src/shared-tree/unhydratedTreeContext.ts

@@ -7,7 +7,7 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type {
 	TreeContextAlpha,
-	TreeBranchAlpha,
+	UntypedTreeViewAlpha,
 	RunTransactionParamsAlpha,
 	TransactionVoidResult,
 	TransactionValueResult,
@@ -24,7 +24,11 @@ export class UnhydratedTreeContext implements TreeContextAlpha {
 	private transactionCount = 0;
 	private constructor() {}
 
-	public isBranch(): this is TreeBranchAlpha {
+	public isBranch(): this is UntypedTreeViewAlpha {
+		return this.isView();
+	}
+
+	public isView(): this is UntypedTreeViewAlpha {
 		return false;
 	}
 

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

@@ -17,6 +17,7 @@ import {
 	type ChangeFamily,
 	type ChangeFamilyEditor,
 	CommitKind,
+	type CustomMetadataTree,
 	type GraphCommit,
 	type RevisionTag,
 	type TaggedChange,
@@ -56,6 +57,10 @@ export type SharedTreeBranchChange<TChange> =
 	| {
 			type: "rebase";
 			change: TaggedChange<TChange> | undefined;
+			/** The commits removed from the head of the branch by this operation */
+			removedCommits: readonly GraphCommit<TChange>[];
+			/** The commits appended to the head of the branch by this operation */
+			newCommits: readonly GraphCommit<TChange>[];
 	  };
 
 /**
@@ -152,7 +157,7 @@ export class SharedTreeBranch<
 		>,
 	) {
 		this.editor = this.changeFamily.buildEditor(mintRevisionTag, (change) =>
-			this.apply(change),
+			this.apply(change, CommitKind.Default, undefined),
 		);
 		this.unsubscribeBranchTrimmer = branchTrimmer?.on("ancestryTrimmed", (commit) => {
 			this.#events.emit("ancestryTrimmed", commit);
@@ -173,9 +178,15 @@ export class SharedTreeBranch<
 	 * Apply a change to this branch.
 	 * @param change - the change to apply
 	 * @param kind - the kind of change to apply
+	 * @param customMetadata - {@link GraphCommit.customMetadata | metadata} to attach to the new commit.
+	 * Callers reconstructing an existing commit, rather than minting one, must pass that commit's metadata.
 	 * @returns the change that was applied and the new head commit of the branch
 	 */
-	public apply(change: TaggedChange<TChange>, kind: CommitKind = CommitKind.Default): void {
+	public apply(
+		change: TaggedChange<TChange>,
+		kind: CommitKind,
+		customMetadata: CustomMetadataTree | undefined,
+	): void {
 		this.assertNotDisposed();
 
 		const revisionTag = change.revision;
@@ -184,6 +195,7 @@ export class SharedTreeBranch<
 		const newHead = mintCommit(this.head, {
 			revision: revisionTag,
 			change: change.change,
+			customMetadata,
 		});
 
 		const changeEvent = {
@@ -213,6 +225,26 @@ export class SharedTreeBranch<
 		return this.head;
 	}
 
+	/**
+	 * Gets the number of commits in this branch.
+	 * This includes commits on ancestor branches but excludes the sentinel commit at the root of all branches.
+	 * @remarks
+	 * This method has linear complexity in the number of commits in the branch.
+	 * See {@link BranchCommitCounter} for a cached version.
+	 */
+	public getCommitCount(): number {
+		let count = 0;
+		for (
+			let commit: GraphCommit<TChange> | undefined = this.head;
+			commit !== undefined;
+			commit = commit.parent
+		) {
+			count++;
+		}
+		// Exclude the sentinel commit that serves as the base to all branches.
+		return count - 1;
+	}
+
 	/**
 	 * Spawn a new branch that is based off of the current state of this branch.
 	 * @param commit - The commit to base the new branch off of. Defaults to the head of this branch.