@fluidframework/tree 2.41.0-338401 → 2.41.0

package/src/shared-tree/independentView.ts

@@ -9,10 +9,12 @@ import {
 	type IIdCompressor,
 	createIdCompressor,
 } from "@fluidframework/id-compressor/internal";
+
 import type { ICodecOptions } from "../codec/index.js";
 import {
 	type RevisionTag,
 	RevisionTagCodec,
+	SchemaVersion,
 	TreeStoredSchemaRepository,
 } from "../core/index.js";
 import {
@@ -23,7 +25,6 @@ import {
 	defaultSchemaPolicy,
 	TreeCompressionStrategy,
 	initializeForest,
-	SchemaCodecVersion,
 } from "../feature-libraries/index.js";
 // eslint-disable-next-line import/no-internal-modules
 import type { Format } from "../feature-libraries/schema-index/formatV1.js";
@@ -32,7 +33,7 @@ import type {
 	ImplicitFieldSchema,
 	TreeViewAlpha,
 } from "../simple-tree/index.js";
-import type { JsonCompatibleReadOnly, JsonCompatible } from "../util/index.js";
+import { type JsonCompatibleReadOnly, type JsonCompatible, Breakable } from "../util/index.js";
 import {
 	buildConfiguredForest,
 	defaultSharedTreeOptions,
@@ -54,11 +55,13 @@ export function independentView<const TSchema extends ImplicitFieldSchema>(
 	config: TreeViewConfiguration<TSchema>,
 	options: ForestOptions & { idCompressor?: IIdCompressor | undefined },
 ): TreeViewAlpha<TSchema> {
+	const breaker = new Breakable("independentView");
 	const idCompressor: IIdCompressor = options.idCompressor ?? createIdCompressor();
 	const mintRevisionTag = (): RevisionTag => idCompressor.generateCompressedId();
 	const revisionTagCodec = new RevisionTagCodec(idCompressor);
 	const schema = new TreeStoredSchemaRepository();
 	const forest = buildConfiguredForest(
+		breaker,
 		options.forest ?? defaultSharedTreeOptions.forest,
 		schema,
 		idCompressor,
@@ -66,6 +69,7 @@ export function independentView<const TSchema extends ImplicitFieldSchema>(
 	const checkout = createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, {
 		forest,
 		schema,
+		breaker,
 	});
 	const out: TreeViewAlpha<TSchema> = new SchematizingSimpleTreeView<TSchema>(
 		checkout,
@@ -88,15 +92,17 @@ export function independentInitializedView<const TSchema extends ImplicitFieldSc
 	options: ForestOptions & ICodecOptions,
 	content: ViewContent,
 ): TreeViewAlpha<TSchema> {
+	const breaker = new Breakable("independentInitializedView");
 	const idCompressor: IIdCompressor = content.idCompressor;
 	const mintRevisionTag = (): RevisionTag => idCompressor.generateCompressedId();
 	const revisionTagCodec = new RevisionTagCodec(idCompressor);
 
 	const fieldBatchCodec = makeFieldBatchCodec(options, 1);
-	const schemaCodec = makeSchemaCodec(options, SchemaCodecVersion.v1);
+	const schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);
 
 	const schema = new TreeStoredSchemaRepository(schemaCodec.decode(content.schema as Format));
 	const forest = buildConfiguredForest(
+		breaker,
 		options.forest ?? defaultSharedTreeOptions.forest,
 		schema,
 		idCompressor,
@@ -118,6 +124,7 @@ export function independentInitializedView<const TSchema extends ImplicitFieldSc
 	const checkout = createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, {
 		forest,
 		schema,
+		breaker,
 	});
 	const out: TreeViewAlpha<TSchema> = new SchematizingSimpleTreeView<TSchema>(
 		checkout,

package/src/shared-tree/index.ts

@@ -50,7 +50,10 @@ export type {
 export { Tree } from "./tree.js";
 export type { RunTransaction } from "./tree.js";
 
-export { TreeAlpha } from "./treeAlpha.js";
+export {
+	TreeAlpha,
+	type TreeIdentifierUtils,
+} from "./treeAlpha.js";
 
 export {
 	independentInitializedView,

package/src/shared-tree/schematizeTree.ts

@@ -19,9 +19,10 @@ import {
 	defaultSchemaPolicy,
 	mapTreeFromCursor,
 } from "../feature-libraries/index.js";
+import type { SchemaCompatibilityTester } from "../simple-tree/index.js";
 import { isReadonlyArray } from "../util/index.js";
+
 import type { ITreeCheckout } from "./treeCheckout.js";
-import type { SchemaCompatibilityTester } from "../simple-tree/index.js";
 
 /**
  * Modify `storedSchema` and invoke `setInitialTree` when it's time to set the tree content.

package/src/shared-tree/schematizingTreeView.ts

@@ -3,12 +3,12 @@
  * Licensed under the MIT License.
  */
 
+import { createEmitter } from "@fluid-internal/client-utils";
 import type {
 	HasListeners,
 	IEmitter,
 	Listenable,
 } from "@fluidframework/core-interfaces/internal";
-import { createEmitter } from "@fluid-internal/client-utils";
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -61,9 +61,9 @@ import {
 	type WithBreakable,
 } from "../util/index.js";
 
+import { CheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
 import { canInitialize, ensureSchema, initialize } from "./schematizeTree.js";
 import type { ITreeCheckout, TreeCheckout } from "./treeCheckout.js";
-import { CheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
 
 /**
  * Creating multiple tree views from the same checkout is not supported. This slot is used to detect if one already

package/src/shared-tree/sharedTree.ts

@@ -3,13 +3,14 @@
  * Licensed under the MIT License.
  */
 
-import { assert, fail } from "@fluidframework/core-utils/internal";
 import type {
 	ErasedType,
 	IFluidHandle,
 	IFluidLoadable,
 } from "@fluidframework/core-interfaces/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type {
 	IChannelView,
 	IFluidSerializer,
@@ -19,7 +20,6 @@ import {
 	UsageError,
 	type ITelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import { type ICodecOptions, noopValidator } from "../codec/index.js";
 import {
@@ -32,6 +32,7 @@ import {
 	MapNodeStoredSchema,
 	ObjectNodeStoredSchema,
 	RevisionTagCodec,
+	SchemaVersion,
 	type TaggedChange,
 	type TreeFieldStoredSchema,
 	type TreeNodeSchemaIdentifier,
@@ -42,12 +43,10 @@ import {
 	makeDetachedFieldIndex,
 	moveToDetachedField,
 } from "../core/index.js";
-
 import {
 	DetachedFieldIndexSummarizer,
 	FieldKinds,
 	ForestSummarizer,
-	SchemaCodecVersion,
 	SchemaSummarizer,
 	TreeCompressionStrategy,
 	buildChunkedForest,
@@ -59,6 +58,8 @@ import {
 	makeSchemaCodec,
 	makeTreeChunker,
 } from "../feature-libraries/index.js";
+// eslint-disable-next-line import/no-internal-modules
+import type { Format } from "../feature-libraries/schema-index/index.js";
 import {
 	type ClonableSchemaAndPolicy,
 	DefaultResubmitMachine,
@@ -86,6 +87,12 @@ import {
 	type ITreeAlpha,
 	type SimpleObjectFieldSchema,
 } from "../simple-tree/index.js";
+import {
+	type Breakable,
+	breakingClass,
+	type JsonCompatible,
+	throwIfBroken,
+} from "../util/index.js";
 
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import { SharedTreeReadonlyChangeEnricher } from "./sharedTreeChangeEnricher.js";
@@ -93,14 +100,6 @@ import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { type TreeCheckout, type BranchableTree, createTreeCheckout } from "./treeCheckout.js";
-import {
-	type Breakable,
-	breakingClass,
-	type JsonCompatible,
-	throwIfBroken,
-} from "../util/index.js";
-// eslint-disable-next-line import/no-internal-modules
-import type { Format } from "../feature-libraries/schema-index/index.js";
 
 /**
  * Copy of data from an {@link ITreePrivate} at some point in time.
@@ -166,7 +165,7 @@ export interface ITreePrivate extends ITreeInternal {
  */
 interface ExplicitCodecVersions extends ExplicitCoreCodecVersions {
 	forest: number;
-	schema: SchemaCodecVersion;
+	schema: SchemaVersion;
 	detachedFieldIndex: number;
 	fieldBatch: number;
 }
@@ -238,7 +237,7 @@ export class SharedTreeKernel
 		const options = { ...defaultSharedTreeOptions, ...optionsParam };
 		const codecVersions = getCodecVersions(options.formatVersion);
 		const schema = new TreeStoredSchemaRepository();
-		const forest = buildConfiguredForest(options.forest, schema, idCompressor);
+		const forest = buildConfiguredForest(breaker, options.forest, schema, idCompressor);
 		const revisionTagCodec = new RevisionTagCodec(idCompressor);
 		const removedRoots = makeDetachedFieldIndex(
 			"repair",
@@ -506,7 +505,7 @@ export function persistedToSimpleSchema(
 	persisted: JsonCompatible,
 	options: ICodecOptions,
 ): SimpleTreeSchema {
-	const schemaCodec = makeSchemaCodec(options, SchemaCodecVersion.v1);
+	const schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);
 	const stored = schemaCodec.decode(persisted as Format);
 	return exportSimpleSchema(stored);
 }
@@ -646,7 +645,10 @@ export interface ForestType extends ErasedType<"ForestType"> {}
  * The "ObjectForest" forest type.
  * @alpha
  */
-export const ForestTypeReference = toForestType(() => buildForest());
+export const ForestTypeReference = toForestType(
+	(breaker: Breakable, schema: TreeStoredSchemaSubscription, idCompressor: IIdCompressor) =>
+		buildForest(breaker, schema),
+);
 
 /**
  * Optimized implementation of forest.
@@ -658,7 +660,7 @@ export const ForestTypeReference = toForestType(() => buildForest());
  * @alpha
  */
 export const ForestTypeOptimized = toForestType(
-	(schema: TreeStoredSchemaSubscription, idCompressor: IIdCompressor) =>
+	(breaker: Breakable, schema: TreeStoredSchemaSubscription, idCompressor: IIdCompressor) =>
 		buildChunkedForest(makeTreeChunker(schema, defaultSchemaPolicy), undefined, idCompressor),
 );
 
@@ -671,9 +673,13 @@ export const ForestTypeOptimized = toForestType(
  * The "ObjectForest" forest type with expensive asserts for debugging.
  * @alpha
  */
-export const ForestTypeExpensiveDebug = toForestType(() => buildForest(undefined, true));
+export const ForestTypeExpensiveDebug = toForestType(
+	(breaker: Breakable, schema: TreeStoredSchemaSubscription) =>
+		buildForest(breaker, schema, undefined, true),
+);
 
 type ForestFactory = (
+	breaker: Breakable,
 	schema: TreeStoredSchemaSubscription,
 	idCompressor: IIdCompressor,
 ) => IEditableForest;
@@ -686,11 +692,12 @@ function toForestType(factory: ForestFactory): ForestType {
  * Build and return a forest of the requested type.
  */
 export function buildConfiguredForest(
+	breaker: Breakable,
 	factory: ForestType,
 	schema: TreeStoredSchemaSubscription,
 	idCompressor: IIdCompressor,
 ): IEditableForest {
-	return (factory as unknown as ForestFactory)(schema, idCompressor);
+	return (factory as unknown as ForestFactory)(breaker, schema, idCompressor);
 }
 
 export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {

package/src/shared-tree/sharedTreeChangeFamily.ts

@@ -4,6 +4,7 @@
  */
 
 import { assert, fail } from "@fluidframework/core-utils/internal";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import type { ICodecFamily, ICodecOptions } from "../codec/index.js";
 import {
@@ -38,7 +39,6 @@ import {
 import { makeSharedTreeChangeCodecFamily } from "./sharedTreeChangeCodecs.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 /**
  * Implementation of {@link ChangeFamily} that combines edits to fields and schema changes.

package/src/shared-tree/tree.ts

@@ -18,9 +18,9 @@ import {
 	type TransactionConstraint,
 } from "../simple-tree/index.js";
 
+import { getCheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import type { ITreeCheckout } from "./treeCheckout.js";
-import { getCheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
 
 /**
  * Provides various functions for interacting with {@link TreeNode}s.

package/src/shared-tree/treeAlpha.ts

@@ -16,8 +16,6 @@ import {
 	TreeBeta,
 	tryGetSchema,
 	createFromCursor,
-	createFromInsertable,
-	cursorFromInsertable,
 	FieldKind,
 	normalizeFieldSchema,
 	type ImplicitFieldSchema,
@@ -39,9 +37,10 @@ import {
 	getStoredKey,
 	getPropertyKeyFromStoredKey,
 	treeNodeApi,
+	getIdentifierFromNode,
 	mapTreeFromNodeData,
 } from "../simple-tree/index.js";
-import type { JsonCompatible } from "../util/index.js";
+import { extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import { noopValidator, type FluidClientVersion, type ICodecOptions } from "../codec/index.js";
 import type { ITreeCursorSynchronous } from "../core/index.js";
 import {
@@ -54,12 +53,124 @@ import {
 	type FieldBatch,
 	type FieldBatchEncodingContext,
 	fluidVersionToFieldBatchCodecWriteVersion,
+	type LocalNodeIdentifier,
 } from "../feature-libraries/index.js";
 import { independentInitializedView, type ViewContent } from "./independentView.js";
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
 import { currentVersion } from "../codec/index.js";
 import { createFromMapTree } from "../simple-tree/index.js";
 
+const identifier: TreeIdentifierUtils = (node: TreeNode): string | undefined => {
+	const nodeIdentifier = getIdentifierFromNode(node, "uncompressed");
+	if (typeof nodeIdentifier === "number") {
+		throw new TypeError("identifier should be uncompressed.");
+	}
+	return nodeIdentifier;
+};
+
+identifier.shorten = (branch: TreeBranch, nodeIdentifier: string): number | undefined => {
+	const nodeKeyManager = (branch as SchematizingSimpleTreeView<ImplicitFieldSchema>)
+		.nodeKeyManager;
+	const localNodeKey = nodeKeyManager.tryLocalizeNodeIdentifier(nodeIdentifier);
+	return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : undefined;
+};
+
+identifier.lengthen = (branch: TreeBranch, nodeIdentifier: number): string => {
+	const nodeKeyManager = (branch as SchematizingSimpleTreeView<ImplicitFieldSchema>)
+		.nodeKeyManager;
+	return nodeKeyManager.stabilizeNodeIdentifier(
+		nodeIdentifier as unknown as LocalNodeIdentifier,
+	);
+};
+
+identifier.getShort = (node: TreeNode): number | undefined => {
+	const shortIdentifier = getIdentifierFromNode(node, "compressed");
+	return typeof shortIdentifier === "number" ? shortIdentifier : undefined;
+};
+
+identifier.create = (branch: TreeBranch): string => {
+	const nodeKeyManager = (branch as SchematizingSimpleTreeView<ImplicitFieldSchema>)
+		.nodeKeyManager;
+	return nodeKeyManager.stabilizeNodeIdentifier(nodeKeyManager.generateLocalNodeIdentifier());
+};
+
+Object.freeze(identifier);
+
+/**
+ * A utility interface for retrieving or converting node identifiers.
+ *
+ * @remarks
+ * This provides methods to:
+ *
+ * - Retrieve long or short identifiers from nodes
+ *
+ * - Convert between long identifiers and short identifiers
+ *
+ * - Generates long identifiers
+ *
+ * @alpha @sealed
+ */
+export interface TreeIdentifierUtils {
+	/**
+	 * Returns the contents of a node's {@link SchemaFactory.identifier} field as a stable identifier.
+	 * If the identifier field does not exist, returns undefined.
+	 *
+	 * @param node - The TreeNode you want to get the identifier from,
+	 */
+	(node: TreeNode): string | undefined;
+
+	/**
+	 * Returns the shortened identifier as a number given long identifier known by the id compressor on the branch if possible.
+	 * Otherwise, it will return the original string identifier provided.
+	 * If the id does not exist, or is unknown by the id compressor, it returns undefined.
+	 *
+	 * This method is the inverse of {@link TreeIdentifierUtils.lengthen}. If you shorten an identifier
+	 * and then immediately pass it to {@link TreeIdentifierUtils.lengthen}, you will get the original string back.
+	 *
+	 * @param branch - TreeBranch from where you get the idCompressor to do the decompression.
+	 * @param nodeIdentifier - the stable identifier that needs to be shortened.
+	 */
+	shorten(branch: TreeBranch, nodeIdentifier: string): number | undefined;
+
+	/**
+	 * Returns the stable id as a string if the identifier is decompressible and known by the id compressor. Otherwise, it will throw an error.
+	 *
+	 * This method is the inverse of {@link TreeIdentifierUtils.shorten}. If you lengthen an identifier
+	 * and then immediately pass it to {@link TreeIdentifierUtils.shorten}, you will get the original short identifier back.
+	 *
+	 * @param branch - TreeBranch from where you want to get the id compressor to do the decompression.
+	 * @param nodeIdentifier - The local identifier that needs to be expanded.
+	 */
+	lengthen(branch: TreeBranch, nodeIdentifier: number): string;
+
+	/**
+	 * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.
+	 * @remarks
+	 * If the node is {@link Unhydrated | hydrated} and its identifier is a valid UUID that was automatically generated by the SharedTree it is part of (or something else using the same {@link @fluidframework/id-compressor#IIdCompressor}), then this will return a process-unique integer corresponding to that identifier.
+	 * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.
+	 * Note that automatically generated identifiers that were accessed before the node was hydrated will return the generated UUID, not the process-unique integer.
+	 *
+	 * If the node's identifier is any other user-provided string, then this will return undefined.
+	 *
+	 * If the node has no identifier (that is, it has no {@link SchemaFactory.identifier | identifier} field), then this returns `undefined`.
+	 *
+	 * If the node has more than one identifier, then this will throw an error.
+	 *
+	 * The returned integer should not be serialized or preserved outside of the current process.
+	 * Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context.
+	 * The same node's identifier may, for example, be different across multiple sessions for the same client and document, or different across two clients in the same session.
+	 */
+	getShort(node: TreeNode): number | undefined;
+
+	/**
+	 * Creates and returns a long identifier.
+	 * The long identifier is a compressible, stable identifier generated by the tree's ID compressor.
+	 *
+	 * @param branch - TreeBranch from where you want to get the id compressor to generate the identifier from.
+	 */
+	create(branch: TreeBranch): string;
+}
+
 /**
  * Extensions to {@link (Tree:interface)} and {@link (TreeBeta:interface)} which are not yet stable.
  * @remarks
@@ -180,7 +291,7 @@ export interface TreeAlpha {
 	 * Additionally using `createIdCompressor` to make an idCompressor is `@legacy` and thus not intended for use in this API surface.
 	 * It would probably make more sense if we provided a way to get an idCompressor from the context of a node,
 	 * which could be optional (and settable if missing) for un0hydrated nodes and required for hydrated ones.
-	 * Add in a stable public APi for creating idCompressors, and a way to get them from a tree (without view schema), and that should address the anticipated use-cases.
+	 * Add in a stable public API for creating idCompressors, and a way to get them from a tree (without view schema), and that should address the anticipated use-cases.
 	 */
 	exportCompressed(
 		tree: TreeNode | TreeLeafValue,
@@ -212,6 +323,11 @@ export interface TreeAlpha {
 		options: { idCompressor?: IIdCompressor } & ICodecOptions,
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 
+	/**
+	 * APIs for creating, converting, and retrieving identifiers.
+	 */
+	readonly identifier: TreeIdentifierUtils;
+
 	/**
 	 * The key of the given node under its parent.
 	 * @remarks
@@ -270,14 +386,10 @@ export const TreeAlpha: TreeAlpha = {
 			? TreeFieldFromImplicitField<TSchema>
 			: TreeNode | TreeLeafValue | undefined
 	> {
-		return createFromInsertable<UnsafeUnknownSchema>(
-			schema,
-			data as InsertableField<UnsafeUnknownSchema>,
-		) as Unhydrated<
-			TSchema extends ImplicitFieldSchema
-				? TreeFieldFromImplicitField<TSchema>
-				: TreeNode | TreeLeafValue | undefined
-		>;
+		// `importConcise` does not need to support all the formats that `create` does.
+		// Perhaps it should error instead of hydrating nodes for example.
+		// For now however, it is a simple wrapper around `create`.
+		return this.create(schema, data as InsertableField<TSchema>);
 	},
 
 	importVerbose<const TSchema extends ImplicitFieldSchema>(
@@ -353,6 +465,8 @@ export const TreeAlpha: TreeAlpha = {
 		return TreeBeta.clone<TSchema>(view.root);
 	},
 
+	identifier,
+
 	key2(node: TreeNode): string | number | undefined {
 		// If the parent is undefined, then this node is under the root field,
 		const parent = treeNodeApi.parent(node);
@@ -396,25 +510,35 @@ function exportConcise(
 	);
 }
 
+/**
+ * Borrow a cursor from a node.
+ * @remarks
+ * The cursor must be put back to its original location before the node is used again.
+ */
 function borrowCursorFromTreeNodeOrValue(
 	node: TreeNode | TreeLeafValue,
 ): ITreeCursorSynchronous {
 	if (isTreeValue(node)) {
-		return cursorFromInsertable<UnsafeUnknownSchema>(
-			tryGetSchema(node) ?? fail(0xad0 /* missing schema */),
-			node,
-		);
+		return cursorFromVerbose(node, {});
 	}
 	const kernel = getKernel(node);
 	const cursor = kernel.getOrCreateInnerNode().borrowCursor();
 	return cursor;
 }
 
+/**
+ * Borrow a cursor from a field.
+ * @remarks
+ * The cursor must be put back to its original location before the node is used again.
+ */
 function borrowFieldCursorFromTreeNodeOrValue(
-	node: TreeNode | TreeLeafValue,
+	node: TreeNode | TreeLeafValue | undefined,
 ): ITreeCursorSynchronous {
+	if (node === undefined) {
+		return cursorForMapTreeField([]);
+	}
 	const cursor = borrowCursorFromTreeNodeOrValue(node);
-	// TODO: avoid copy
+	// TODO: avoid copy: borrow cursor from field instead.
 	const mapTree = mapTreeFromCursor(cursor);
 	return cursorForMapTreeField([mapTree]);
 }

package/src/shared-tree/treeCheckout.ts

@@ -276,8 +276,9 @@ export function createTreeCheckout(
 		disposeForksAfterTransaction?: boolean;
 	},
 ): TreeCheckout {
-	const forest = args?.forest ?? buildForest();
+	const breaker = args?.breaker ?? new Breakable("TreeCheckout");
 	const schema = args?.schema ?? new TreeStoredSchemaRepository();
+	const forest = args?.forest ?? buildForest(breaker, schema);
 	const defaultCodecOptions = { jsonValidator: noopValidator };
 	const defaultFieldBatchVersion = 1;
 	const changeFamily =
@@ -312,7 +313,7 @@ export function createTreeCheckout(
 		idCompressor,
 		args?.removedRoots,
 		args?.logger,
-		args?.breaker,
+		breaker,
 		args?.disposeForksAfterTransaction,
 	);
 }

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

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { Listenable } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import { type TelemetryEventBatcher, measure } from "@fluidframework/telemetry-utils/internal";
 
@@ -21,9 +23,6 @@ import {
 	tagRollbackInverse,
 	type RebaseStatsWithDuration,
 } from "../core/index.js";
-import type { Listenable } from "@fluidframework/core-interfaces";
-import { createEmitter } from "@fluid-internal/client-utils";
-
 import { hasSome, defineLazyCachedProperty } from "../util/index.js";
 
 /**
@@ -171,7 +170,7 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 	}
 
 	/**
-	 * @returns the commit at the head of this branch.
+	 * Gets the commit at the head of this branch.
 	 */
 	public getHead(): GraphCommit<TChange> {
 		return this.head;

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

@@ -4,15 +4,17 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+
 import {
 	type ChangeRebaser,
 	type GraphCommit,
 	replaceChange,
 	type RevisionTag,
 } from "../core/index.js";
+
+import type { SharedTreeBranchChange } from "./branch.js";
 import type { ChangeEnricherReadonlyCheckout } from "./changeEnricher.js";
 import { TransactionEnricher } from "./transactionEnricher.js";
-import type { SharedTreeBranchChange } from "./branch.js";
 
 /**
  * Utility for enriching commits from a {@link Branch} before these commits are applied and submitted.

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

@@ -4,8 +4,10 @@
  */
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
+
 import type { GraphCommit, TaggedChange } from "../core/index.js";
 import { disposeSymbol, hasSome } from "../util/index.js";
+
 import type { ChangeEnricherReadonlyCheckout, ResubmitMachine } from "./index.js";
 
 /**

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

@@ -627,8 +627,10 @@ export class EditManager<
 	}
 
 	/**
-	 * @returns The length of the longest branch maintained by this EditManager.
+	 * Gets the length of the longest branch maintained by this `EditManager`.
 	 * This may be the length of a peer branch or the local branch.
+	 *
+	 * @remarks
 	 * The length is counted from the lowest common ancestor with the trunk such that a fully sequenced branch would
 	 * have length zero.
 	 */
@@ -825,7 +827,7 @@ export interface SummaryData<TChangeset> {
 }
 
 /**
- * @returns the path from the base of a branch to its head
+ * Gets the path from the base of a branch to its head.
  */
 function getPathFromBase<TCommit extends { parent?: TCommit }>(
 	branchHead: TCommit,

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

@@ -4,6 +4,7 @@
  */
 
 import type { IIdCompressor } from "@fluidframework/id-compressor";
+
 import {
 	type ICodecFamily,
 	type ICodecOptions,

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

@@ -6,6 +6,7 @@
 import { bufferToString } from "@fluid-internal/client-utils";
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type {
 	ISummaryTreeWithStats,
 	ITelemetryContext,
@@ -23,7 +24,6 @@ import type {
 	SummaryElementParser,
 	SummaryElementStringifier,
 } from "./sharedTreeCore.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 const stringKey = "String";