@fluidframework/tree 2.116.1 → 2.118.0

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(

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

@@ -11,6 +11,7 @@ import { SessionIdSchema } from "../core/index.js";
 
 import {
 	EditManagerFormatVersion,
+	type EncodedSequencedCommit,
 	type EncodedSummarySessionBranch,
 	SequencedCommit,
 	SummarySessionBranch,
@@ -22,17 +23,21 @@ const noAdditionalProps: ObjectOptions = { additionalProperties: false };
 /* eslint-disable @typescript-eslint/explicit-function-return-type */
 
 export interface EncodedEditManager<TChangeset> {
-	readonly trunk: readonly Readonly<SequencedCommit<TChangeset>>[];
+	readonly trunk: readonly Readonly<EncodedSequencedCommit<TChangeset>>[];
 	readonly branches: readonly [SessionId, Readonly<EncodedSummarySessionBranch<TChangeset>>][];
 	readonly version:
 		| typeof EditManagerFormatVersion.v1
 		| typeof EditManagerFormatVersion.v2
 		| typeof EditManagerFormatVersion.v3
 		| typeof EditManagerFormatVersion.v4
-		| typeof EditManagerFormatVersion.v6;
+		| typeof EditManagerFormatVersion.v6
+		| typeof EditManagerFormatVersion.v7;
 }
 
-export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+export const EncodedEditManager = <ChangeSchema extends TSchema>(
+	tChange: ChangeSchema,
+	includeCustomMetadata: boolean,
+) =>
 	Type.Object(
 		{
 			version: Type.Union([
@@ -41,9 +46,12 @@ export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: Change
 				Type.Literal(EditManagerFormatVersion.v3),
 				Type.Literal(EditManagerFormatVersion.v4),
 				Type.Literal(EditManagerFormatVersion.v6),
+				Type.Literal(EditManagerFormatVersion.v7),
 			]),
-			trunk: Type.Array(SequencedCommit(tChange)),
-			branches: Type.Array(Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange)])),
+			trunk: Type.Array(SequencedCommit(tChange, includeCustomMetadata)),
+			branches: Type.Array(
+				Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange, includeCustomMetadata)]),
+			),
 		},
 		noAdditionalProps,
 	);

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

@@ -28,8 +28,8 @@ export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: Change
 		{
 			version: Type.Literal(EditManagerFormatVersion.vSharedBranches),
 			originator: SessionIdSchema,
-			main: EncodedSharedBranch(tChange),
-			branches: Type.Optional(Type.Array(EncodedSharedBranch(tChange))),
+			main: EncodedSharedBranch(tChange, true),
+			branches: Type.Optional(Type.Array(EncodedSharedBranch(tChange, true))),
 		},
 		noAdditionalProps,
 	);

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

@@ -9,8 +9,11 @@ export {
 	type SharedTreeBranchChange,
 	type SharedTreeBranchEvents,
 	type BranchId,
+	type BranchTrimmingEvents,
 } from "./branch.js";
 
+export { BranchCommitCounter } from "./branchCommitCounter.js";
+
 export {
 	type ChangeProcessor,
 	type OnPop,

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

@@ -15,10 +15,12 @@ import type {
 import {
 	type JsonCompatibleReadOnlyObject,
 	JsonCompatibleReadOnlySchema,
+	type Mutable,
 } from "../util/index.js";
 
 import type { MessageDecodingContext, MessageEncodingContext } from "./messageCodecs.js";
-import type { MessageFormatVersion } from "./messageFormat.js";
+import { MessageFormatVersion } from "./messageFormat.js";
+import { decodeCustomMetadataTree, encodeCustomMetadataTree } from "./customMetadataCodec.js";
 import { Message } from "./messageFormatV1ToV4.js";
 import type { DecodedMessage } from "./messageTypes.js";
 
@@ -35,9 +37,15 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 		| typeof MessageFormatVersion.v2
 		| typeof MessageFormatVersion.v3
 		| typeof MessageFormatVersion.v4
-		| typeof MessageFormatVersion.v6,
+		| typeof MessageFormatVersion.v6
+		| typeof MessageFormatVersion.v7,
 ): CodecAndSchema<DecodedMessage<TChangeset>, MessageEncodingContext, MessageDecodingContext> {
-	const schema = Message(changeCodec.encodedSchema ?? JsonCompatibleReadOnlySchema);
+	// Persisted commit metadata was introduced in v7; older formats must not write the field.
+	const supportsCustomMetadata = version >= MessageFormatVersion.v7;
+	const schema = Message(
+		changeCodec.encodedSchema ?? JsonCompatibleReadOnlySchema,
+		supportsCustomMetadata,
+	);
 	return {
 		schema,
 		encode: (
@@ -50,7 +58,7 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 				0xc69 /* Only commit messages to main are supported */,
 			);
 			const { commit, sessionId: originatorId } = decoded;
-			return {
+			const encoded: Mutable<Message & JsonCompatibleReadOnlyObject & Versioned> = {
 				revision: revisionTagCodec.encode(commit.revision, {
 					originatorId,
 					idCompressor: context.idCompressor,
@@ -67,12 +75,16 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 				}),
 				version,
 			};
+			if (supportsCustomMetadata && commit.customMetadata !== undefined) {
+				encoded.customMetadata = encodeCustomMetadataTree(commit.customMetadata);
+			}
+			return encoded;
 		},
 		decode: (
 			encoded: Message & JsonCompatibleReadOnlyObject & Versioned,
 			context: MessageDecodingContext,
 		): DecodedMessage<TChangeset> => {
-			const { revision: encodedRevision, originatorId, changeset } = encoded;
+			const { revision: encodedRevision, originatorId, changeset, customMetadata } = encoded;
 
 			const revision = revisionTagCodec.decode(encodedRevision, {
 				originatorId,
@@ -92,6 +104,7 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 						idCompressor: context.idCompressor,
 						isSummary: false,
 					}),
+					customMetadata: decodeCustomMetadataTree(customMetadata),
 				},
 				sessionId: originatorId,
 			};

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

@@ -14,9 +14,10 @@ import type {
 	EncodedRevisionTag,
 	RevisionTag,
 } from "../core/index.js";
-import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
+import type { JsonCompatibleReadOnlyObject, Mutable } from "../util/index.js";
 
 import { decodeBranchId, encodeBranchId } from "./branchIdCodec.js";
+import { decodeCustomMetadataTree, encodeCustomMetadataTree } from "./customMetadataCodec.js";
 import type { MessageDecodingContext, MessageEncodingContext } from "./messageCodecs.js";
 import type { MessageFormatVersion } from "./messageFormat.js";
 import { Message } from "./messageFormatVSharedBranches.js";
@@ -51,7 +52,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 						isSummary: false,
 					};
 
-					return {
+					const encoded: Mutable<Message & JsonCompatibleReadOnlyObject & Versioned> = {
 						revision: revisionTagCodec.encode(message.commit.revision, {
 							originatorId: message.sessionId,
 							idCompressor: context.idCompressor,
@@ -63,6 +64,10 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 						branchId: encodeBranchId(context.idCompressor, message.branchId),
 						version,
 					};
+					if (message.commit.customMetadata !== undefined) {
+						encoded.customMetadata = encodeCustomMetadataTree(message.commit.customMetadata);
+					}
+					return encoded;
 				}
 				case "branch": {
 					return {
@@ -87,6 +92,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 				changeset,
 				branchId: encodedBranchId,
 				branchName: encodedBranchName,
+				customMetadata,
 			} = encoded;
 
 			const changeContext: ChangeEncodingContext = {
@@ -120,6 +126,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 						idCompressor: context.idCompressor,
 						isSummary: false,
 					}),
+					customMetadata: decodeCustomMetadataTree(customMetadata),
 				},
 				branchId,
 				sessionId: originatorId,

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

@@ -125,6 +125,18 @@ export function makeMessageCodecBuilder<TChangeset>(): VersionDispatchingCodecBu
 					MessageFormatVersion.v6,
 				),
 		},
+		{
+			minVersionForCollab: FluidClientVersion.v2_117,
+			formatVersion: MessageFormatVersion.v7,
+			codec: (options: MessageCodecBuilderOptions<TChangeset>) =>
+				makeV1ToV4CodecWithVersion(
+					options.changeCodecs.resolve(
+						options.dependentChangeFormatVersion.lookup(MessageFormatVersion.v7),
+					),
+					options.revisionTagCodec,
+					MessageFormatVersion.v7,
+				),
+		},
 		{
 			minVersionForCollab: undefined,
 			formatVersion: MessageFormatVersion.vSharedBranches,

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

@@ -52,6 +52,11 @@ export const MessageFormatVersion = strictEnum("MessageFormatVersion", {
 	 * 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.
@@ -63,5 +68,6 @@ export const supportedMessageFormatVersions: ReadonlySet<MessageFormatVersion> =
 	MessageFormatVersion.v3,
 	MessageFormatVersion.v4,
 	MessageFormatVersion.v6,
+	MessageFormatVersion.v7,
 	MessageFormatVersion.vSharedBranches,
 ]);