@fluidframework/tree 2.116.1 → 2.118.0

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.

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

@@ -0,0 +1,103 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+
+import type { ChangeFamilyEditor, RevisionTag } from "../core/index.js";
+import type { SharedTreeBranch, SharedTreeBranchChange } from "./branch.js";
+
+/**
+ * A utility class that counts the number of commits in a branch and keeps the count updated as the branch changes.
+ *
+ * @remarks
+ * This class has no inside knowledge of what the commits represent.
+ * It is therefore oblivious to any scheme where some root commit is considered "special" and should not be counted.
+ */
+export class BranchCommitCounter<
+	TEditor extends ChangeFamilyEditor,
+	TChange,
+	TChangeProcessingContext,
+> {
+	private unsubscribeAfterChange?: () => void;
+	private unsubscribeAncestryTrimmed?: () => void;
+	private commitCountInitialized: boolean = false;
+	private cachedCommitCount: number = 0;
+
+	public constructor(
+		private readonly branch: SharedTreeBranch<TEditor, TChange, TChangeProcessingContext>,
+	) {}
+
+	public dispose(): void {
+		this.unsubscribeFromBranch();
+	}
+
+	/**
+	 * Gets the number of commits in the branch.
+	 */
+	public get count(): number {
+		if (!this.commitCountInitialized) {
+			this.cachedCommitCount = this.branch.getCommitCount();
+			this.subscribeToBranch();
+			this.commitCountInitialized = true;
+		}
+		return this.cachedCommitCount;
+	}
+
+	private subscribeToBranch(): void {
+		this.unsubscribeFromBranch();
+		this.unsubscribeAfterChange = this.branch.events.on(
+			"afterChange",
+			this.onAfterBranchChange,
+		);
+		this.unsubscribeAncestryTrimmed = this.branch.events.on(
+			"ancestryTrimmed",
+			this.onAncestryTrimmed,
+		);
+	}
+
+	private unsubscribeFromBranch(): void {
+		this.unsubscribeAfterChange?.();
+		this.unsubscribeAfterChange = undefined;
+		this.unsubscribeAncestryTrimmed?.();
+		this.unsubscribeAncestryTrimmed = undefined;
+	}
+
+	private readonly onAfterBranchChange = (event: SharedTreeBranchChange<TChange>): void => {
+		if (!this.commitCountInitialized) {
+			return;
+		}
+
+		switch (event.type) {
+			case "append": {
+				this.cachedCommitCount += event.newCommits.length;
+				return;
+			}
+			case "remove": {
+				this.cachedCommitCount -= event.removedCommits.length;
+				return;
+			}
+			case "rebase": {
+				this.cachedCommitCount += event.newCommits.length;
+				this.cachedCommitCount -= event.removedCommits.length;
+				return;
+			}
+			default: {
+				unreachableCase(event);
+			}
+		}
+	};
+
+	private readonly onAncestryTrimmed = (trimmedRevisions: RevisionTag[]): void => {
+		if (!this.commitCountInitialized) {
+			return;
+		}
+
+		assert(
+			this.cachedCommitCount >= trimmedRevisions.length,
+			0xd35 /* Trimmed more commits than exist in the branch */,
+		);
+		this.cachedCommitCount = this.cachedCommitCount - trimmedRevisions.length;
+	};
+}

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

@@ -0,0 +1,42 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { CustomMetadataTree } from "../core/index.js";
+import type { Mutable } from "../util/index.js";
+
+import type { EncodedCustomMetadataTree } from "./customMetadataFormat.js";
+
+export function encodeCustomMetadataTree(tree: CustomMetadataTree): EncodedCustomMetadataTree {
+	const encoded: Mutable<EncodedCustomMetadataTree> = {};
+	if (tree.metadata !== undefined) {
+		encoded.m = tree.metadata;
+	}
+	if (tree.children.length > 0) {
+		encoded.c = tree.children.map(encodeCustomMetadataTree);
+	}
+	return encoded;
+}
+
+export function decodeCustomMetadataTree(
+	encoded: EncodedCustomMetadataTree | undefined,
+): CustomMetadataTree | undefined {
+	if (encoded === undefined) {
+		return undefined;
+	}
+	const decoded = decodeNode(encoded);
+	// A tree in which no node supplied metadata carries no information.
+	return hasMetadata(decoded) ? decoded : undefined;
+}
+
+function decodeNode(encoded: EncodedCustomMetadataTree): CustomMetadataTree {
+	return {
+		metadata: encoded.m,
+		children: encoded.c?.map(decodeNode) ?? [],
+	};
+}
+
+function hasMetadata(node: CustomMetadataTree): boolean {
+	return node.metadata !== undefined || node.children.some(hasMetadata);
+}

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

@@ -0,0 +1,39 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import * as Type from "@sinclair/typebox";
+
+import {
+	type JsonCompatibleReadOnlyObject,
+	JsonCompatibleReadOnlySchema,
+} from "../util/index.js";
+
+/**
+ * The persisted form of a {@link CustomMetadataTree}.
+ * @remarks
+ * The property names (`m` for metadata, `c` for children) are abbreviated and both are optional because
+ * this rides on every annotated op and occupies summary space for as long as its commit survives.
+ */
+// Declared as a type alias rather than an interface so that it satisfies the index signature of
+// `JsonCompatibleReadOnlyObject`, which the encoded message and summary types are constrained to.
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type EncodedCustomMetadataTree = {
+	readonly m?: JsonCompatibleReadOnlyObject;
+	readonly c?: readonly EncodedCustomMetadataTree[];
+};
+
+export const EncodedCustomMetadataTree = Type.Recursive((Self) =>
+	Type.Object(
+		{
+			m: Type.Optional(
+				Type.Unsafe<JsonCompatibleReadOnlyObject>(
+					Type.Record(Type.String(), JsonCompatibleReadOnlySchema),
+				),
+			),
+			c: Type.Optional(Type.Array(Self)),
+		},
+		{ additionalProperties: false },
+	),
+) as unknown as Type.TSchema;