@fluidframework/tree 2.116.0 → 2.117.0

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;

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

@@ -17,6 +17,7 @@ import { BTree } from "@tylerbu/sorted-btree-es6";
 import {
 	type ChangeFamily,
 	type ChangeFamilyEditor,
+	CommitKind,
 	type GraphCommit,
 	type RevisionTag,
 	findAncestor,
@@ -134,6 +135,7 @@ export class EditManager<
 		this.trunkBase = {
 			revision: rootRevision,
 			change: changeFamily.rebaser.compose([]),
+			customMetadata: undefined,
 		};
 
 		if (logger !== undefined) {
@@ -348,6 +350,11 @@ export class EditManager<
 		// so rebase them accordingly. This is necessary to prevent peer branches from referencing any evicted commits.
 		mainBranch.trimHistory(latestEvicted, sequenceId);
 
+		// Custom metadata shares the lifetime of its commit, so it must be dropped when the commit is
+		// trimmed. The new trunk base stays reachable as the sentinel for the remaining history, so its
+		// metadata is cleared rather than trapped; fully evicted commits get the throwing trap below.
+		(newTrunkBase as Mutable<typeof newTrunkBase>).customMetadata = undefined;
+
 		// Only the last trimmed commit, which is the new trunk base, should remain accessible.
 		for (const commit of trimmedCommits.slice(0, -1)) {
 			Reflect.defineProperty(commit, "change", {
@@ -363,6 +370,10 @@ export class EditManager<
 			Reflect.defineProperty(commit, "parent", {
 				get: () => fail(0xa60 /* Should not access 'parent' property of an evicted commit */),
 			});
+			Reflect.defineProperty(commit, "customMetadata", {
+				get: () =>
+					fail(0xd36 /* Should not access 'customMetadata' property of an evicted commit */),
+			});
 		}
 
 		// Dropping the parent field removes (transitively) all references to the evicted commits so they can be garbage collected.
@@ -386,11 +397,13 @@ export class EditManager<
 		// Trimming the trunk before serializing ensures that the trunk data in the summary is as minimal as possible.
 		this.trimHistory();
 
+		const mainBranch = this.getSharedBranch("main");
 		const minSeqNumberToSummarize: SequenceId = {
 			sequenceNumber: brand(this.minimumSequenceNumber + 1),
 		};
-		let minBaseSeqId: SequenceId = minSeqNumberToSummarize;
-		const mainBranch = this.getSharedBranch("main");
+		let minBaseSeqId: SequenceId = this.retainHistory
+			? (mainBranch.sequenceIdToCommit.minKey() ?? minimumPossibleSequenceId)
+			: minSeqNumberToSummarize;
 		const branches = new Map<BranchId, SharedBranchSummaryData<TChangeset>>();
 		for (const [branchId, branch] of this.sharedBranches) {
 			if (branchId !== "main") {
@@ -822,7 +835,11 @@ class SharedBranch<TEditor extends ChangeFamilyEditor, TChangeset, TChangeProces
 		} else {
 			// Otherwise, push the changes to the peer local branch and merge the branch into the trunk.
 			for (const newCommit of newCommits) {
-				peerLocalBranch.apply(tagChange(newCommit.change, newCommit.revision));
+				peerLocalBranch.apply(
+					tagChange(newCommit.change, newCommit.revision),
+					CommitKind.Default,
+					newCommit.customMetadata,
+				);
 			}
 			const result = this.trunk.merge(peerLocalBranch);
 			if (result !== undefined) {
@@ -1089,6 +1106,7 @@ class SharedBranch<TEditor extends ChangeFamilyEditor, TChangeset, TChangeProces
 				revision: c.revision,
 				sequenceNumber: metadata.sequenceId.sequenceNumber,
 				sessionId: metadata.sessionId,
+				customMetadata: c.customMetadata,
 			};
 			if (metadata.sequenceId.indexInBatch !== undefined) {
 				commit.indexInBatch = metadata.sequenceId.indexInBatch;
@@ -1114,6 +1132,7 @@ class SharedBranch<TEditor extends ChangeFamilyEditor, TChangeset, TChangeProces
 								change: c.change,
 								revision: c.revision,
 								sessionId,
+								customMetadata: c.customMetadata,
 							};
 							return commit;
 						}),

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

@@ -108,6 +108,18 @@ export function makeEditManagerCodecBuilder<TChangeset>(): VersionDispatchingCod
 					EditManagerFormatVersion.v6,
 				),
 		},
+		{
+			minVersionForCollab: FluidClientVersion.v2_117,
+			formatVersion: EditManagerFormatVersion.v7,
+			codec: (options: EditManagerCodecOptions<TChangeset>) =>
+				makeV1toV4andV6CodecWithVersion(
+					options.changeCodecs.resolve(
+						options.dependentChangeFormatVersion.lookup(EditManagerFormatVersion.v7),
+					),
+					options.revisionTagCodec,
+					EditManagerFormatVersion.v7,
+				),
+		},
 		{
 			minVersionForCollab: undefined,
 			formatVersion: EditManagerFormatVersion.vSharedBranches,

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

@@ -22,6 +22,7 @@ import {
 } from "../util/index.js";
 
 import { decodeBranchId, encodeBranchId } from "./branchIdCodec.js";
+import { decodeCustomMetadataTree, encodeCustomMetadataTree } from "./customMetadataCodec.js";
 import type { SharedBranchSummaryData } from "./editManager.js";
 import type {
 	Commit,
@@ -71,8 +72,9 @@ function encodeCommit<TChangeset, T extends Commit<TChangeset>>(
 	>,
 	commit: T,
 	context: ChangeEncodingContext,
+	includeCustomMetadata: boolean,
 ) {
-	return {
+	const encoded = {
 		...commit,
 		revision: revisionTagCodec.encode(commit.revision, {
 			originatorId: commit.sessionId,
@@ -82,6 +84,16 @@ function encodeCommit<TChangeset, T extends Commit<TChangeset>>(
 		}),
 		change: changeCodec.encode(commit.change, { ...context, revision: commit.revision }),
 	};
+	// Rebuilt rather than spread through, both to convert it to the persisted form and so that a client
+	// writing an older format never emits a field that format does not define.
+	if (encoded.customMetadata === undefined) {
+		const { customMetadata: _, ...withoutMetadata } = encoded;
+		return withoutMetadata;
+	}
+	const { customMetadata, ...rest } = encoded;
+	return includeCustomMetadata
+		? { ...rest, customMetadata: encodeCustomMetadataTree(customMetadata) }
+		: rest;
 }
 
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -112,6 +124,7 @@ function decodeCommit<TChangeset, T extends EncodedCommit<JsonCompatibleReadOnly
 		...commit,
 		revision,
 		change: changeCodec.decode(commit.change, { ...context, revision }),
+		customMetadata: decodeCustomMetadataTree(commit.customMetadata),
 	};
 }
 
@@ -131,16 +144,23 @@ export function encodeSharedBranch<TChangeset>(
 	data: SharedBranchSummaryData<TChangeset>,
 	context: EditManagerEncodingContext,
 	originatorId: SessionId | undefined,
+	includeCustomMetadata: boolean,
 ): EncodedSharedBranch<TChangeset> {
 	const json: Mutable<EncodedSharedBranch<TChangeset>> = {
 		trunk: data.trunk.map((commit) =>
-			encodeCommit(changeCodec, revisionTagCodec, commit, {
-				originatorId: commit.sessionId,
-				idCompressor: context.idCompressor,
-				schema: context.schema,
-				revision: undefined,
-				isSummary: context.isSummary,
-			}),
+			encodeCommit(
+				changeCodec,
+				revisionTagCodec,
+				commit,
+				{
+					originatorId: commit.sessionId,
+					idCompressor: context.idCompressor,
+					schema: context.schema,
+					revision: undefined,
+					isSummary: context.isSummary,
+				},
+				includeCustomMetadata,
+			),
 		),
 		peers: Array.from(data.peerLocalBranches.entries(), ([sessionId, branch]) => [
 			sessionId,
@@ -152,13 +172,19 @@ export function encodeSharedBranch<TChangeset>(
 					isSummary: context.isSummary,
 				}),
 				commits: branch.commits.map((commit) =>
-					encodeCommit(changeCodec, revisionTagCodec, commit, {
-						originatorId: commit.sessionId,
-						idCompressor: context.idCompressor,
-						schema: context.schema,
-						revision: undefined,
-						isSummary: context.isSummary,
-					}),
+					encodeCommit(
+						changeCodec,
+						revisionTagCodec,
+						commit,
+						{
+							originatorId: commit.sessionId,
+							idCompressor: context.idCompressor,
+							schema: context.schema,
+							revision: undefined,
+							isSummary: context.isSummary,
+						},
+						includeCustomMetadata,
+					),
 				),
 			},
 		]),

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

@@ -19,6 +19,7 @@ import {
 	type EditManagerEncodingContext,
 } from "./editManagerCodecsCommons.js";
 import { EncodedEditManager } from "./editManagerFormatV1toV4.js";
+import { EditManagerFormatVersion } from "./editManagerFormatCommons.js";
 
 /**
  * Create the provided version of the {@link EditManager} codec (which encodes it's {@link SummaryData}).
@@ -47,7 +48,11 @@ export function makeV1toV4andV6CodecWithVersion<TChangeset>(
 	EditManagerEncodingContext,
 	EditManagerDecodingContext
 > {
-	const schema = EncodedEditManager(changeCodec.encodedSchema ?? JsonCompatibleReadOnlySchema);
+	const includeCustomMetadata = version >= EditManagerFormatVersion.v7;
+	const schema = EncodedEditManager(
+		changeCodec.encodedSchema ?? JsonCompatibleReadOnlySchema,
+		includeCustomMetadata,
+	);
 
 	const codec: CodecAndSchema<
 		SummaryData<TChangeset>,
@@ -65,6 +70,7 @@ export function makeV1toV4andV6CodecWithVersion<TChangeset>(
 				data.main,
 				context,
 				data.originator,
+				includeCustomMetadata,
 			);
 			const encoded: EncodedEditManager<TChangeset> = {
 				trunk: mainBranch.trunk,

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

@@ -59,6 +59,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 				data.main,
 				context,
 				data.originator,
+				true,
 			);
 			assert(
 				data.originator !== undefined,
@@ -79,6 +80,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 							branch,
 							context,
 							data.originator,
+							true,
 						),
 					);
 				}

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

@@ -8,6 +8,7 @@ import * as Type from "@sinclair/typebox";
 import type { ObjectOptions, Static, TSchema } from "@sinclair/typebox";
 
 import {
+	type CustomMetadataTree,
 	type EncodedRevisionTag,
 	type RevisionTag,
 	RevisionTagSchema,
@@ -16,6 +17,7 @@ import {
 import { type Brand, brandedNumberType, strictEnum, type Values } from "../util/index.js";
 
 import type { EncodedBranchId } from "./branch.js";
+import { EncodedCustomMetadataTree } from "./customMetadataFormat.js";
 
 /**
  * Contains a single change to the `SharedTree` and associated metadata.
@@ -28,6 +30,8 @@ export interface Commit<TChangeset> {
 	readonly change: TChangeset;
 	/** An identifier representing the session/user/client that made this commit */
 	readonly sessionId: SessionId;
+	/** Arbitrary, application-defined metadata stored alongside this commit */
+	readonly customMetadata: CustomMetadataTree | undefined;
 }
 
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
@@ -35,6 +39,7 @@ export type EncodedCommit<TChangeset> = {
 	readonly revision: EncodedRevisionTag;
 	readonly change: TChangeset;
 	readonly sessionId: SessionId;
+	readonly customMetadata?: EncodedCustomMetadataTree;
 };
 
 const noAdditionalProps: ObjectOptions = { additionalProperties: false };
@@ -42,18 +47,27 @@ const noAdditionalProps: ObjectOptions = { additionalProperties: false };
 // Many of the return types in this module are intentionally derived, rather than explicitly specified.
 /* eslint-disable @typescript-eslint/explicit-function-return-type */
 
-const CommitBase = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+const CommitBase = <ChangeSchema extends TSchema>(
+	tChange: ChangeSchema,
+	includeCustomMetadata: boolean,
+) =>
 	Type.Object({
 		revision: RevisionTagSchema,
 		change: tChange,
 		sessionId: SessionIdSchema,
+		...(includeCustomMetadata
+			? { customMetadata: Type.Optional(EncodedCustomMetadataTree) }
+			: {}),
 	});
+
 /**
  * @privateRemarks Commits are generally encoded from `GraphCommit`s, which often contain extra data.
  * This `noAdditionalProps` is especially important in that light.
  */
-const Commit = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
-	Type.Composite([CommitBase(tChange)], noAdditionalProps);
+const Commit = <ChangeSchema extends TSchema>(
+	tChange: ChangeSchema,
+	includeCustomMetadata: boolean,
+) => Type.Composite([CommitBase(tChange, includeCustomMetadata)], noAdditionalProps);
 
 export type SeqNumber = Brand<number, "edit-manager.SeqNumber">;
 const SeqNumber = brandedNumberType<SeqNumber>({ multipleOf: 1 });
@@ -70,8 +84,14 @@ export type SequenceId = Static<typeof SequenceId>;
  */
 export interface SequencedCommit<TChangeset> extends Commit<TChangeset>, SequenceId {}
 
-export const SequencedCommit = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
-	Type.Composite([CommitBase(tChange), SequenceId], noAdditionalProps);
+/** The persisted counterpart of {@link SequencedCommit}. */
+export type EncodedSequencedCommit<TChangeset> = EncodedCommit<TChangeset> & SequenceId;
+
+export const SequencedCommit = <ChangeSchema extends TSchema>(
+	tChange: ChangeSchema,
+	includeCustomMetadata: boolean,
+) =>
+	Type.Composite([CommitBase(tChange, includeCustomMetadata), SequenceId], noAdditionalProps);
 
 /**
  * A branch off of the trunk for use in summaries.
@@ -86,14 +106,17 @@ export interface SummarySessionBranch<TChangeset> {
 
 export interface EncodedSummarySessionBranch<TChangeset> {
 	readonly base: EncodedRevisionTag;
-	readonly commits: Commit<TChangeset>[];
+	readonly commits: EncodedCommit<TChangeset>[];
 }
 
-export const SummarySessionBranch = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+export const SummarySessionBranch = <ChangeSchema extends TSchema>(
+	tChange: ChangeSchema,
+	includeCustomMetadata: boolean,
+) =>
 	Type.Object(
 		{
 			base: RevisionTagSchema,
-			commits: Type.Array(Commit(tChange)),
+			commits: Type.Array(Commit(tChange, includeCustomMetadata)),
 		},
 		noAdditionalProps,
 	);
@@ -104,11 +127,14 @@ export interface EncodedSharedBranch<TChangeset> {
 	readonly author?: string;
 	readonly session?: SessionId;
 	readonly base?: EncodedRevisionTag;
-	readonly trunk: readonly Readonly<SequencedCommit<TChangeset>>[];
+	readonly trunk: readonly Readonly<EncodedSequencedCommit<TChangeset>>[];
 	readonly peers: readonly [SessionId, Readonly<EncodedSummarySessionBranch<TChangeset>>][];
 }
 
-export const EncodedSharedBranch = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+export const EncodedSharedBranch = <ChangeSchema extends TSchema>(
+	tChange: ChangeSchema,
+	includeCustomMetadata: boolean,
+) =>
 	Type.Object(
 		{
 			id: Type.Optional(Type.Number()),
@@ -116,8 +142,10 @@ export const EncodedSharedBranch = <ChangeSchema extends TSchema>(tChange: Chang
 			session: Type.Optional(SessionIdSchema),
 			author: Type.Optional(Type.String()),
 			base: Type.Optional(RevisionTagSchema),
-			trunk: Type.Array(SequencedCommit(tChange)),
-			peers: Type.Array(Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange)])),
+			trunk: Type.Array(SequencedCommit(tChange, includeCustomMetadata)),
+			peers: Type.Array(
+				Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange, includeCustomMetadata)]),
+			),
 		},
 		noAdditionalProps,
 	);
@@ -163,6 +191,11 @@ export const EditManagerFormatVersion = strictEnum("editManager.FormatVersion",
 	 * Adds support for "no change" constraints.
 	 */
 	v6: 6,
+	/**
+	 * Introduced and made available for writing in 2.117.0.
+	 * Adds support for {@link GraphCommit.customMetadata | persisted commit metadata}.
+	 */
+	v7: 7,
 	/**
 	 * Not yet released.
 	 * Only used for testing shared branches.
@@ -175,6 +208,7 @@ export const supportedEditManagerFormatVersions: ReadonlySet<EditManagerFormatVe
 		EditManagerFormatVersion.v3,
 		EditManagerFormatVersion.v4,
 		EditManagerFormatVersion.v6,
+		EditManagerFormatVersion.v7,
 		EditManagerFormatVersion.vSharedBranches,
 	]);
 export const editManagerFormatVersions: ReadonlySet<EditManagerFormatVersion> = new Set(