@fluidframework/tree 2.111.0 → 2.113.0-411909

package/src/shared-tree/sharedTree.ts

@@ -336,6 +336,7 @@ export class SharedTreeKernel
 			viewWith: this.viewWith.bind(this),
 			viewSharedBranchWith: this.viewBranchWith.bind(this),
 			createSharedBranch: this.createSharedBranch.bind(this),
+			getSharedBranchName: this.getSharedBranchName.bind(this),
 			getSharedBranchIds: this.getSharedBranchIds.bind(this),
 			kernel: this,
 		};
@@ -639,6 +640,20 @@ export interface SharedTreeOptions
 	 * See {@link IncrementalEncodingPolicy}.
 	 */
 	shouldEncodeIncrementally?: IncrementalEncodingPolicy;
+
+	/**
+	 * When `true`, prevents trunk commits from being trimmed/evicted, even after they fall outside
+	 * the collaboration window.
+	 *
+	 * @defaultValue `false`
+	 *
+	 * @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.
+	 */
+	readonly retainHistory?: boolean;
 }
 
 export interface SharedTreeOptionsInternal
@@ -771,6 +786,7 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	healUnresolvableIdentifiersOnDecode: false,
 	writeVersionOverrides: new Map(),
 	allowPossiblyIncompatibleWriteVersionOverrides: false,
+	retainHistory: false,
 };
 
 /**

package/src/shared-tree/sharedTreeChangeFamily.ts

@@ -245,7 +245,13 @@ export function hasSchemaChange(change: SharedTreeChange): boolean {
 	return change.changes.some((innerChange) => innerChange.type === "schema");
 }
 
-function mapDataChanges(
+/**
+ * Applies a mapping function to all data changes within a {@link SharedTreeChange}.
+ * @param change - The change to map over.
+ * @param map - The mapping function to apply to each data change.
+ * @returns A new {@link SharedTreeChange} with the mapped data changes.
+ */
+export function mapDataChanges(
 	change: SharedTreeChange,
 	map: (change: ModularChangeset) => ModularChangeset,
 ): SharedTreeChange {

package/src/shared-tree/transactionMinimize.ts

@@ -0,0 +1,74 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import { fieldKinds, minimizeModularChangeset } from "../feature-libraries/index.js";
+import { ChangeProcessorApplicability } from "../shared-tree-core/index.js";
+import type { TransactionPostProcessor } from "../simple-tree/index.js";
+
+import { mapDataChanges } from "./sharedTreeChangeFamily.js";
+import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
+import { createTransactionPostProcessor } from "./transactionPostProcessor.js";
+
+/**
+ * "Minimizes" a {@link SharedTreeChange} so that it contains no extraneous
+ * information, i.e. no data that has no net effect on the document.
+ *
+ * @remarks
+ * This iterates over the change's constituent {@link ModularChangeset}s,
+ * replacing each with its {@link minimizeModularChangeset | minimized} form.
+ * At most one data change is allowed in the change currently as a limitation
+ * of the minimization implementation, so this function throws a UsageError
+ * if more than one data change is present.
+ *
+ * Schema changes are left unchanged.
+ */
+function minimizeSharedTreeChange(change: SharedTreeChange): SharedTreeChange {
+	const countOfDataChanges = change.changes.filter(
+		(innerChange) => innerChange.type === "data",
+	).length;
+	if (countOfDataChanges > 1) {
+		throw new UsageError(
+			`At most one edit group can be minimized, but ${countOfDataChanges} were found. To workaround this limitation, pair at most one content edit with any schema changes.`,
+		);
+	}
+	return mapDataChanges(change, (dataChange) =>
+		minimizeModularChangeset(dataChange, fieldKinds),
+	);
+}
+
+/**
+ * A {@link TransactionPostProcessor | post-processor} that "minimizes" the change
+ * produced when a transaction is committed, so that the resulting squashed change
+ * contains no extraneous information.
+ *
+ * @remarks
+ * Supply this via {@link RunTransactionParamsAlpha.postProcessor} when {@link RunTransaction | running a transaction}.
+ * "Extraneous information" includes, for example, data for nodes that were both
+ * created and removed within the transaction, or changes whose effects cancel
+ * out to nothing. Minimizing the change reduces the size of the edit that is
+ * submitted to (and stored by) the service without altering the observable
+ * effect of the transaction.
+ *
+ * The current implementation is limited and is unable to guarantee that the
+ * resulting change is fully minimized if multiple distinct edit groups are
+ * present in the transaction. Transaction edit groups are divided by schema
+ * changes, so this limitation is only relevant for transactions that contain
+ * one or more schema changes and content edits on both sides. In such cases,
+ * the implementation will throw a usage error:
+ * "At most one edit group can be minimized..."
+ *
+ * @deprecated Note: minimization is not yet implemented. For now this is a
+ * no-op that leaves the squashed change unchanged, so supplying it currently
+ * has no observable effect beyond reserving the behavior. A real
+ * implementation will be provided in a future change.
+ *
+ * @alpha
+ */
+export const minimize: TransactionPostProcessor = createTransactionPostProcessor({
+	applicability: ChangeProcessorApplicability.IfOutermost,
+	processChange: minimizeSharedTreeChange,
+});

package/src/shared-tree/treeCheckout.ts

@@ -6,8 +6,7 @@
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { IFluidHandle, Listenable } from "@fluidframework/core-interfaces/internal";
 import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
-import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
-import { isStableId } from "@fluidframework/id-compressor/internal";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 import { type TelemetryLoggerExt, UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -52,12 +51,12 @@ import {
 	type ChangeMetadata,
 	type LabelTree,
 	type TransactionLabels,
-	type ChangeEncodingContext,
 	type ReadOnlyDetachedFieldIndex,
 	makeAnonChange,
 	type TaggedChange,
 	deltaFieldMapHasVisibleChanges,
 	findCommonAncestor,
+	rebaseBranch,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -119,6 +118,7 @@ import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamil
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { extractTransactionChangeProcessor } from "./transactionPostProcessor.js";
+import { SerializedChange } from "./serializedChange.js";
 
 /**
  * Yields all defined (non-`undefined`) labels from a {@link LabelTree}, depth-first.
@@ -317,7 +317,7 @@ export function createTreeCheckout(
 		codecOptions?: Partial<CodecWriteOptions>;
 	},
 ): TreeCheckout {
-	const breaker = args?.breaker ?? new Breakable("TreeCheckout");
+	const breaker = args?.breaker ?? new Breakable("TreeCheckout", args?.logger);
 	const schema = args?.schema ?? new TreeStoredSchemaRepository();
 	const forest = args?.forest ?? buildForest(breaker, schema);
 	const defaultCodecOptions: CodecWriteOptions = {
@@ -530,7 +530,8 @@ export class TreeCheckout implements ITreeCheckout {
 		),
 		/** Optional logger for telemetry. */
 		private readonly logger?: TelemetryLoggerExt,
-		public readonly breaker: Breakable = new Breakable("TreeCheckout"),
+		public readonly breaker: Breakable = new Breakable("TreeCheckout", logger),
+		public readonly disposeForksAfterTransaction = true,
 	) {
 		this.#transaction = this.createTransactionStack(branch);
 		this.editLock = new EditLock(this.#transaction.activeBranchEditor);
@@ -763,24 +764,16 @@ export class TreeCheckout implements ITreeCheckout {
 					kind,
 					isLocal: true,
 					getChange: () => {
-						const context: ChangeEncodingContext = {
-							idCompressor: this.idCompressor,
-							originatorId: this.idCompressor.localSessionId,
-							revision,
-							isSummary: false,
-						};
-						const encodedChange = this.changeFamily.codecs.resolve(4).encode(change, context);
-
 						assert(
 							commit.parent !== undefined,
 							0xca4 /* Expected applied commit to be parented */,
 						);
-						return {
-							version: 1,
+						return SerializedChange.V1.encode(
+							this.idCompressor,
+							this.changeFamily,
+							change,
 							revision,
-							originatorId: this.idCompressor.localSessionId,
-							change: encodedChange,
-						} satisfies SerializedChange;
+						);
 					},
 					getRevertible: (onDisposed) => getRevertible?.(onDisposed),
 					label: this.labelTreeNode?.label,
@@ -859,24 +852,13 @@ export class TreeCheckout implements ITreeCheckout {
 	 */
 	@throwIfBroken
 	public applySerializedChange(serializedChange: JsonCompatibleReadOnly): void {
-		if (!isSerializedChange(serializedChange)) {
-			throw new UsageError(`Cannot apply change. Invalid serialized change format.`);
-		}
-		const { revision, originatorId, change } = serializedChange;
-		if (originatorId !== this.idCompressor.localSessionId) {
-			throw new UsageError(
-				`Cannot apply change. A serialized changed must be applied to the same SharedTree as it was created from.`,
-			);
-		}
-		const context: ChangeEncodingContext = {
-			idCompressor: this.idCompressor,
-			originatorId: this.idCompressor.localSessionId,
-			revision,
-			isSummary: false,
-		};
-		const decodedChange = this.changeFamily.codecs.resolve(4).decode(change, context);
+		const change = SerializedChange.V1.decode(
+			this.idCompressor,
+			this.changeFamily,
+			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(tagChange(decodedChange, revision));
+		this.#transaction.branch.apply(change);
 	}
 
 	// #region TreeBranchAlpha
@@ -1219,7 +1201,7 @@ export class TreeCheckout implements ITreeCheckout {
 
 		const branch = this.#transaction.activeBranch.fork();
 		const storedSchema = this.storedSchema.clone();
-		const forkBreaker = new Breakable("TreeCheckout");
+		const forkBreaker = new Breakable("TreeCheckout", this.logger);
 		const forest = this.forest.clone(storedSchema, forkBreaker);
 		const checkout = new TreeCheckout(
 			branch,
@@ -1308,6 +1290,30 @@ export class TreeCheckout implements ITreeCheckout {
 		return targetPath.length > 0;
 	}
 
+	public computeNetChangeIfRebasedOnto(
+		branch: TreeBranch,
+	): JsonCompatibleReadOnly | undefined {
+		const branchCheckout = getCheckout(branch);
+		const rebased = rebaseBranch(
+			this.mintRevisionTag,
+			this.changeFamily.rebaser,
+			this.#transaction.branch.getHead(),
+			branchCheckout.#transaction.branch.getHead(),
+		);
+
+		if (rebased.sourceChange === undefined) {
+			return undefined;
+		}
+		const revision = this.mintRevisionTag();
+		return SerializedChange.V1.encode(
+			this.idCompressor,
+			this.changeFamily,
+			rebased.sourceChange,
+			revision,
+			undefined,
+		);
+	}
+
 	public merge(branch: TreeBranch): void;
 	public merge(branch: TreeBranch, disposeMerged: boolean): void;
 	public merge(branch: TreeBranch, disposeMerged = true): void {
@@ -1770,27 +1776,6 @@ function verboseFromCursor(
 	};
 }
 
-interface SerializedChange {
-	version: 1;
-	revision: RevisionTag;
-	change: JsonCompatibleReadOnly;
-	originatorId: SessionId;
-}
-
-function isSerializedChange(value: unknown): value is SerializedChange {
-	if (typeof value !== "object" || value === null) {
-		return false;
-	}
-	const change = value as Partial<SerializedChange>;
-	return (
-		change.version === 1 &&
-		(change.revision === "root" || typeof change.revision === "number") &&
-		typeof change.originatorId === "string" &&
-		isStableId(change.originatorId) &&
-		change.change !== undefined
-	);
-}
-
 /**
  * Enumerates through a shared tree change, looking for schema change and field changes that result in visible changes to the tree (e.g. an insert, move, delete).
  * This function also considers changes to detached roots to be visible changes, but not renames of roots or builds of new roots.

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

@@ -9,6 +9,7 @@ import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { SessionId } from "@fluidframework/id-compressor";
 import {
 	TelemetryEventBatcher,
+	UsageError,
 	type TelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 import { BTree } from "@tylerbu/sorted-btree-es6";
@@ -117,6 +118,7 @@ export class EditManager<
 	 * @param localSessionId - the id of the local session that will be used for local commits
 	 * @param mintRevisionTag - a function which generates globally unique revision tags
 	 * @param onSharedBranchCreated - called when a new shared branch is created. This is not called for the main branch.
+	 * @param retainHistory - when `true`, trunk commits are never trimmed/evicted.
 	 */
 	public constructor(
 		public readonly changeFamily: TChangeFamily,
@@ -124,6 +126,7 @@ export class EditManager<
 		private readonly mintRevisionTag: () => RevisionTag,
 		private readonly onSharedBranchCreated?: (branchId: BranchId) => void,
 		logger?: TelemetryLoggerExt,
+		private readonly retainHistory: boolean = false,
 	) {
 		this.trunkBase = {
 			revision: rootRevision,
@@ -149,15 +152,23 @@ export class EditManager<
 			this.telemetryEventBatcher,
 		);
 
-		this.createAndAddSharedBranch("main", undefined, undefined, mainTrunk);
+		this.createAndAddSharedBranch("main", "main", undefined, undefined, mainTrunk);
 	}
 
 	public getLocalBranch(branchId: BranchId): SharedTreeBranch<TEditor, TChangeset> {
 		return this.getSharedBranch(branchId).localBranch;
 	}
 
+	public getSharedBranchName(branchId: BranchId): string | undefined {
+		return this.getSharedBranch(branchId).branchName;
+	}
+
 	private getSharedBranch(branchId: BranchId): SharedBranch<TEditor, TChangeset> {
-		return this.sharedBranches.get(branchId) ?? fail(0xc56 /* Branch does not exist */);
+		const branch = this.sharedBranches.get(branchId);
+		if (branch === undefined) {
+			throw new UsageError("No shared branch with such ID");
+		}
+		return branch;
 	}
 
 	/**
@@ -268,6 +279,11 @@ export class EditManager<
 	 * if any commits on the trunk are unreferenced and unneeded for future computation; those found are evicted from the trunk.
 	 */
 	private trimHistory(): void {
+		if (this.retainHistory) {
+			// When history retention is enabled, trunk commits are never evicted.
+			return;
+		}
+
 		/** The sequence id of the most recent commit on the trunk that will be trimmed */
 		let trunkTailSequenceId: SequenceId = {
 			sequenceNumber: this.minimumSequenceNumber,
@@ -397,6 +413,7 @@ export class EditManager<
 			for (const [branchId, branchData] of data.branches) {
 				const branch = this.createSharedBranch(
 					branchId,
+					branchData.name,
 					branchData.session,
 					mainBranch,
 					mainBranch.trunk.fork(),
@@ -444,6 +461,7 @@ export class EditManager<
 		sessionId: SessionId,
 		referenceSequenceNumber: SeqNumber,
 		branchId: BranchId,
+		branchName?: string,
 	): void {
 		if (sessionId === this.localSessionId) {
 			assert(this.sharedBranches.has(branchId), 0xc59 /* Expected branch to already exist */);
@@ -452,13 +470,14 @@ export class EditManager<
 
 		const mainBranch = this.getSharedBranch("main");
 		const branchTrunk = mainBranch.rebasePeer(sessionId, referenceSequenceNumber).fork();
-		this.createAndAddSharedBranch(branchId, sessionId, mainBranch, branchTrunk);
+		this.createAndAddSharedBranch(branchId, branchName, sessionId, mainBranch, branchTrunk);
 	}
 
-	public addNewBranch(branchId: BranchId): void {
+	public addNewBranch(branchId: BranchId, branchName?: string): void {
 		const main = this.getSharedBranch("main") ?? fail(0xc5a /* Main branch must exist */);
 		this.createAndAddSharedBranch(
 			branchId,
+			branchName,
 			this.localSessionId,
 			main,
 			this.getLocalBranch("main").fork(),
@@ -477,11 +496,18 @@ export class EditManager<
 
 	private createAndAddSharedBranch(
 		branchId: BranchId,
+		branchName: string | undefined,
 		sessionId: SessionId | undefined,
 		parent: SharedBranch<TEditor, TChangeset> | undefined,
 		branch: SharedTreeBranch<TEditor, TChangeset>,
 	): SharedBranch<TEditor, TChangeset> {
-		const sharedBranch = this.createSharedBranch(branchId, sessionId, parent, branch);
+		const sharedBranch = this.createSharedBranch(
+			branchId,
+			branchName,
+			sessionId,
+			parent,
+			branch,
+		);
 		this.addSharedBranch(branchId, sharedBranch);
 		return sharedBranch;
 	}
@@ -509,6 +535,7 @@ export class EditManager<
 
 	private createSharedBranch(
 		branchId: BranchId,
+		branchName: string | undefined,
 		sessionId: SessionId | undefined,
 		parent: SharedBranch<TEditor, TChangeset> | undefined,
 		branch: SharedTreeBranch<TEditor, TChangeset>,
@@ -517,6 +544,7 @@ export class EditManager<
 			parent,
 			branch,
 			branchId,
+			branchName,
 			sessionId,
 			minimumPossibleSequenceId,
 			this.changeFamily,
@@ -689,6 +717,7 @@ class SharedBranch<TEditor extends ChangeFamilyEditor, TChangeset> {
 		public readonly parentBranch: SharedBranch<TEditor, TChangeset> | undefined,
 		public readonly trunk: SharedTreeBranch<TEditor, TChangeset>,
 		private readonly id: BranchId,
+		public readonly branchName: string | undefined,
 		private readonly sessionId: SessionId | undefined,
 		baseCommitSequenceId: SequenceId,
 		private readonly changeFamily: ChangeFamily<TEditor, TChangeset>,
@@ -1076,7 +1105,14 @@ class SharedBranch<TEditor extends ChangeFamilyEditor, TChangeset> {
 
 		const trunkBase =
 			this.parentBranch === undefined ? undefined : forkPointFromMainTrunk.revision;
-		return { trunk, peerLocalBranches, base: trunkBase, id: this.id, session: this.sessionId };
+		return {
+			trunk,
+			peerLocalBranches,
+			base: trunkBase,
+			id: this.id,
+			name: this.branchName,
+			session: this.sessionId,
+		};
 	}
 
 	public loadSummaryData(

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

@@ -167,7 +167,7 @@ export const EditManagerFormatVersion = strictEnum("editManager.FormatVersion",
 	 * Not yet released.
 	 * Only used for testing shared branches.
 	 */
-	vSharedBranches: "shared-branches|v0.1",
+	vSharedBranches: "shared-branches|v0.2",
 });
 export type EditManagerFormatVersion = Values<typeof EditManagerFormatVersion>;
 export const supportedEditManagerFormatVersions: ReadonlySet<EditManagerFormatVersion> =

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

@@ -68,6 +68,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 					return {
 						originatorId: message.sessionId,
 						branchId: encodeBranchId(context.idCompressor, message.branchId),
+						branchName: message.branchName,
 						version,
 					};
 				}
@@ -85,6 +86,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 				originatorId,
 				changeset,
 				branchId: encodedBranchId,
+				branchName: encodedBranchName,
 			} = encoded;
 
 			const changeContext: ChangeEncodingContext = {
@@ -97,7 +99,12 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 			const branchId = decodeBranchId(context.idCompressor, encodedBranchId, changeContext);
 
 			if (changeset === undefined) {
-				return { type: "branch", sessionId: originatorId, branchId };
+				return {
+					type: "branch",
+					sessionId: originatorId,
+					branchId,
+					branchName: encodedBranchName,
+				};
 			}
 
 			assert(encodedRevision !== undefined, 0xc6a /* Commit messages must have a revision */);

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

@@ -56,7 +56,7 @@ export const MessageFormatVersion = strictEnum("MessageFormatVersion", {
 	 * Not yet released.
 	 * Only used for testing shared branches.
 	 */
-	vSharedBranches: "shared-branches|v0.1",
+	vSharedBranches: "shared-branches|v0.2",
 });
 export type MessageFormatVersion = Values<typeof MessageFormatVersion>;
 export const supportedMessageFormatVersions: ReadonlySet<MessageFormatVersion> = new Set([

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

@@ -30,8 +30,17 @@ export interface Message {
 	 */
 	readonly changeset?: JsonCompatibleReadOnly;
 
+	/**
+	 * Unique ID associated with the branch.
+	 */
 	readonly branchId?: EncodedBranchId;
 
+	/**
+	 * Application-defined name of the branch, if any.
+	 * Not guaranteed to be unique.
+	 */
+	readonly branchName?: string;
+
 	/**
 	 * The version of the message format.
 	 */
@@ -46,5 +55,6 @@ export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 		originatorId: SessionIdSchema,
 		changeset: Type.Optional(tChange),
 		branchId: Type.Optional(Type.Number()),
+		branchName: Type.Optional(Type.String()),
 		version: Type.Literal(MessageFormatVersion.vSharedBranches),
 	});

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

@@ -24,4 +24,5 @@ export interface CommitMessage<TChange> extends MessageBase {
 export interface BranchMessage extends MessageBase {
 	type: "branch";
 	branchId: BranchId;
+	branchName?: string;
 }

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

@@ -11,6 +11,7 @@ import type {
 	IIdCompressor,
 	SessionId,
 	SessionSpaceCompressedId,
+	StableId,
 } from "@fluidframework/id-compressor";
 import type {
 	IExperimentalIncrementalSummaryContext,
@@ -23,7 +24,7 @@ import type {
 	IChannelView,
 	IFluidSerializer,
 } from "@fluidframework/shared-object-base/internal";
-import { createChildLogger } from "@fluidframework/telemetry-utils/internal";
+import { createChildLogger, UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { CodecWriteOptions, DependentFormatVersion, IJsonCodec } from "../codec/index.js";
 import {
@@ -78,6 +79,11 @@ export interface SharedTreeCoreOptionsInternal extends CodecWriteOptions {
 	 * See {@link SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode}.
 	 */
 	readonly healUnresolvableIdentifiersOnDecode?: boolean;
+
+	/**
+	 * {@inheritDoc SharedTreeOptions.retainHistory}
+	 */
+	readonly retainHistory?: boolean;
 }
 
 export interface EnrichmentConfig<TChange> {
@@ -124,6 +130,8 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 
 	private readonly schemaAndPolicy: ClonableSchemaAndPolicy;
 
+	private static readonly maxBranchNameLength = 1024;
+
 	/**
 	 * @param summarizables - Summarizers for all indexes used by this tree
 	 * @param changeFamily - The change family
@@ -179,6 +187,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			this.mintRevisionTag,
 			(branchId) => this.registerSharedBranch(branchId),
 			rebaseLogger,
+			options.retainHistory ?? false,
 		);
 
 		this.registerSharedBranch("main");
@@ -391,9 +400,9 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		this.getResubmitMachine(branchId).onCommitSubmitted(enrichedCommit);
 	}
 
-	protected submitBranchCreation(branchId: BranchId): void {
+	protected submitBranchCreation(branchId: BranchId, branchName?: string): void {
 		this.submitMessage(
-			{ type: "branch", sessionId: this.editManager.localSessionId, branchId },
+			{ type: "branch", sessionId: this.editManager.localSessionId, branchId, branchName },
 			this.schemaAndPolicy,
 		);
 	}
@@ -471,6 +480,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 						messagesSessionId,
 						brand(envelope.referenceSequenceNumber),
 						message.branchId,
+						message.branchName,
 					);
 					break;
 				}
@@ -519,21 +529,34 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			.filter((id): id is SessionSpaceCompressedId => id !== "main")
 			.map((id) => this.idCompressor.decompress(id));
 	}
-	public createSharedBranch(): string {
+	public createSharedBranch(branchName?: string): string {
+		if (branchName !== undefined && branchName.length > SharedTreeCore.maxBranchNameLength) {
+			throw new UsageError(
+				`Branch name is too long: ${branchName.length} > maxBranchNameLength`,
+			);
+		}
 		const branchId = this.idCompressor.generateCompressedId();
-		this.addBranch(branchId);
-		this.submitBranchCreation(branchId);
+		this.addBranch(branchId, branchName);
+		this.submitBranchCreation(branchId, branchName);
 		return this.idCompressor.decompress(branchId);
 	}
 
-	protected addBranch(branchId: BranchId): void {
-		this.editManager.addNewBranch(branchId);
+	protected addBranch(branchId: BranchId, branchName?: string): void {
+		this.editManager.addNewBranch(branchId, branchName);
 	}
 
 	public getSharedBranch(branchId: BranchId): SharedTreeBranch<TEditor, TChange> {
 		return this.editManager.getLocalBranch(branchId);
 	}
 
+	public getSharedBranchName(branchId: string): string | undefined {
+		const compressedId = this.idCompressor.tryRecompress(branchId as StableId);
+		if (compressedId === undefined) {
+			throw new UsageError(`No branch found with id: ${branchId}`);
+		}
+		return this.editManager.getSharedBranchName(compressedId);
+	}
+
 	public didAttach(): void {
 		this.detachedRevision = undefined;
 	}
@@ -574,7 +597,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				break;
 			}
 			case "branch": {
-				this.submitBranchCreation(message.branchId);
+				this.submitBranchCreation(message.branchId, message.branchName);
 				break;
 			}
 			default: {
@@ -631,7 +654,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				break;
 			}
 			case "branch": {
-				this.editManager.addNewBranch(message.branchId);
+				this.editManager.addNewBranch(message.branchId, message.branchName);
 				break;
 			}
 			default: {