@fluidframework/tree 2.33.2 → 2.40.0

package/src/shared-tree/schematizeTree.ts

@@ -6,7 +6,6 @@
 import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
 
 import {
-	AllowedUpdateType,
 	CursorLocationType,
 	type ITreeCursorSynchronous,
 	type TreeStoredSchema,
@@ -21,9 +20,8 @@ import {
 	mapTreeFromCursor,
 } from "../feature-libraries/index.js";
 import { isReadonlyArray } from "../util/index.js";
-
 import type { ITreeCheckout } from "./treeCheckout.js";
-import { toStoredSchema, type ViewSchema } from "../simple-tree/index.js";
+import type { SchemaCompatibilityTester } from "../simple-tree/index.js";
 
 /**
  * Modify `storedSchema` and invoke `setInitialTree` when it's time to set the tree content.
@@ -98,10 +96,6 @@ export enum UpdateType {
 	 * Already compatible, no update needed.
 	 */
 	None,
-	/**
-	 * Empty: needs initializing.
-	 */
-	Initialize,
 	/**
 	 * Schema can be upgraded leaving tree as is.
 	 */
@@ -112,9 +106,11 @@ export enum UpdateType {
 	Incompatible,
 }
 
+/**
+ * Returns how compatible updating checkout's schema is with the viewSchema.
+ */
 export function evaluateUpdate(
-	viewSchema: ViewSchema,
-	allowedSchemaModifications: AllowedUpdateType,
+	viewSchema: SchemaCompatibilityTester,
 	checkout: ITreeCheckout,
 ): UpdateType {
 	const compatibility = viewSchema.checkCompatibility(checkout.storedSchema);
@@ -124,11 +120,6 @@ export function evaluateUpdate(
 		return UpdateType.None;
 	}
 
-	// eslint-disable-next-line no-bitwise
-	if (allowedSchemaModifications & AllowedUpdateType.Initialize && canInitialize(checkout)) {
-		return UpdateType.Initialize;
-	}
-
 	if (!compatibility.canUpgrade) {
 		// Existing stored schema permits trees which are incompatible with the view schema, so schema can not be updated
 		return UpdateType.Incompatible;
@@ -137,10 +128,7 @@ export function evaluateUpdate(
 	assert(!compatibility.canView, 0x8bd /* unexpected case */);
 	assert(compatibility.canUpgrade, 0x8be /* unexpected case */);
 
-	// eslint-disable-next-line no-bitwise
-	return allowedSchemaModifications & AllowedUpdateType.SchemaCompatible
-		? UpdateType.SchemaCompatible
-		: UpdateType.Incompatible;
+	return UpdateType.SchemaCompatible;
 }
 
 export function canInitialize(checkout: ITreeCheckout): boolean {
@@ -209,7 +197,7 @@ export function initialize(checkout: ITreeCheckout, treeContent: TreeStoredConte
 }
 
 /**
- * Ensure a {@link ITreeCheckout} can be used with a given {@link ViewSchema}.
+ * Ensure a {@link ITreeCheckout} can be used with a given {@link SchemaCompatibilityTester}.
  *
  * @remarks
  * It is up to the caller to ensure that compatibility is reevaluated if the checkout's stored schema is edited in the future.
@@ -221,18 +209,10 @@ export function initialize(checkout: ITreeCheckout, treeContent: TreeStoredConte
  * @returns true iff checkout now is compatible with `viewSchema`.
  */
 export function ensureSchema(
-	viewSchema: ViewSchema,
-	allowedSchemaModifications: AllowedUpdateType,
+	viewSchema: SchemaCompatibilityTester,
 	checkout: ITreeCheckout,
-	treeContent: TreeStoredContent | undefined,
 ): boolean {
-	let possibleModifications = allowedSchemaModifications;
-	if (treeContent === undefined) {
-		// Clear bit for Initialize if initial tree is not provided.
-		// eslint-disable-next-line no-bitwise
-		possibleModifications &= ~AllowedUpdateType.Initialize;
-	}
-	const updatedNeeded = evaluateUpdate(viewSchema, possibleModifications, checkout);
+	const updatedNeeded = evaluateUpdate(viewSchema, checkout);
 	switch (updatedNeeded) {
 		case UpdateType.None: {
 			return true;
@@ -241,17 +221,7 @@ export function ensureSchema(
 			return false;
 		}
 		case UpdateType.SchemaCompatible: {
-			checkout.updateSchema(toStoredSchema(viewSchema.schema));
-			return true;
-		}
-		case UpdateType.Initialize: {
-			if (treeContent === undefined) {
-				return false;
-			}
-			// TODO:
-			// When this becomes a more proper out of schema adapter, editing should be made lazy.
-			// This will improve support for readonly documents, cross version collaboration and attribution.
-			initialize(checkout, treeContent);
+			checkout.updateSchema(viewSchema.viewSchemaAsStored);
 			return true;
 		}
 		default: {

package/src/shared-tree/schematizingTreeView.ts

@@ -12,7 +12,7 @@ import { createEmitter } from "@fluid-internal/client-utils";
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { AllowedUpdateType, anchorSlot, type SchemaPolicy } from "../core/index.js";
+import { anchorSlot, type SchemaPolicy } from "../core/index.js";
 import {
 	type NodeIdentifierManager,
 	defaultSchemaPolicy,
@@ -30,13 +30,12 @@ import {
 	getTreeNodeForField,
 	setField,
 	normalizeFieldSchema,
-	ViewSchema,
+	SchemaCompatibilityTester,
 	type InsertableContent,
 	type TreeViewConfiguration,
 	mapTreeFromNodeData,
 	prepareContentForHydration,
 	comparePersistedSchemaInternal,
-	toStoredSchema,
 	type TreeViewAlpha,
 	type InsertableField,
 	type ReadableField,
@@ -98,7 +97,7 @@ export class SchematizingSimpleTreeView<
 		IEmitter<TreeViewEvents & TreeBranchEvents> &
 		HasListeners<TreeViewEvents & TreeBranchEvents> = createEmitter();
 
-	private readonly viewSchema: ViewSchema;
+	private readonly viewSchema: SchemaCompatibilityTester;
 
 	private readonly unregisterCallbacks = new Set<() => void>();
 
@@ -133,7 +132,11 @@ export class SchematizingSimpleTreeView<
 			allowUnknownOptionalFields: createUnknownOptionalFieldPolicy(this.rootFieldSchema),
 		};
 
-		this.viewSchema = new ViewSchema(this.schemaPolicy, {}, this.rootFieldSchema);
+		this.viewSchema = new SchemaCompatibilityTester(
+			this.schemaPolicy,
+			{},
+			this.rootFieldSchema,
+		);
 		// This must be initialized before `update` can be called.
 		this.currentCompatibility = {
 			canView: false,
@@ -182,7 +185,7 @@ export class SchematizingSimpleTreeView<
 
 			prepareContentForHydration(mapTree, this.checkout.forest);
 			initialize(this.checkout, {
-				schema: toStoredSchema(this.viewSchema.schema),
+				schema: this.viewSchema.viewSchemaAsStored,
 				initialTree: mapTree === undefined ? undefined : cursorForMapTreeNode(mapTree),
 			});
 		});
@@ -204,15 +207,7 @@ export class SchematizingSimpleTreeView<
 		}
 
 		this.runSchemaEdit(() => {
-			const result = ensureSchema(
-				this.viewSchema,
-				AllowedUpdateType.SchemaCompatible,
-				this.checkout,
-				{
-					schema: toStoredSchema(this.viewSchema.schema),
-					initialTree: undefined,
-				},
-			);
+			const result = ensureSchema(this.viewSchema, this.checkout);
 			assert(result, 0x8bf /* Schema upgrade should always work if canUpgrade is set. */);
 		});
 	}
@@ -502,12 +497,12 @@ export function getCheckout(context: TreeBranch): TreeCheckout {
 }
 
 /**
- * Creates a view that self-disposes whenenever the stored schema changes.
+ * Creates a view that self-disposes whenever the stored schema changes.
  * This may only be called when the schema is already known to be compatible (typically via ensureSchema).
  */
 export function requireSchema(
 	checkout: ITreeCheckout,
-	viewSchema: ViewSchema,
+	viewSchema: SchemaCompatibilityTester,
 	onDispose: () => void,
 	nodeKeyManager: NodeIdentifierManager,
 	schemaPolicy: FullSchemaPolicy,

package/src/shared-tree/sharedTree.ts

@@ -13,6 +13,7 @@ import type { IChannelStorageService } from "@fluidframework/datastore-definitio
 import type {
 	IChannelView,
 	IFluidSerializer,
+	SharedKernel,
 } from "@fluidframework/shared-object-base/internal";
 import {
 	UsageError,
@@ -46,6 +47,7 @@ import {
 	DetachedFieldIndexSummarizer,
 	FieldKinds,
 	ForestSummarizer,
+	SchemaCodecVersion,
 	SchemaSummarizer,
 	TreeCompressionStrategy,
 	buildChunkedForest,
@@ -54,6 +56,7 @@ import {
 	jsonableTreeFromFieldCursor,
 	makeFieldBatchCodec,
 	makeMitigatedChangeFamily,
+	makeSchemaCodec,
 	makeTreeChunker,
 } from "../feature-libraries/index.js";
 import {
@@ -90,7 +93,14 @@ 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, throwIfBroken } from "../util/index.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.
@@ -156,7 +166,7 @@ export interface ITreePrivate extends ITreeInternal {
  */
 interface ExplicitCodecVersions extends ExplicitCoreCodecVersions {
 	forest: number;
-	schema: number;
+	schema: SchemaCodecVersion;
 	detachedFieldIndex: number;
 	fieldBatch: number;
 }
@@ -186,18 +196,35 @@ function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
 	return versions;
 }
 
+/**
+ * The type SharedTree's kernel's view must implement so what when its merged with the underling SharedObject's API it fully implements the required tree API surface ({@link ITreePrivate }).
+ */
+export type SharedTreeKernelView = Omit<ITreePrivate, keyof (IChannelView & IFluidLoadable)>;
+
 /**
  * SharedTreeCore, configured with a good set of indexes and field kinds which will maintain compatibility over time.
  *
  * TODO: detail compatibility requirements.
  */
 @breakingClass
-export class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange> {
+export class SharedTreeKernel
+	extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>
+	implements SharedKernel
+{
 	public readonly checkout: TreeCheckout;
 	public get storedSchema(): TreeStoredSchemaRepository {
 		return this.checkout.storedSchema;
 	}
 
+	/**
+	 * The app-facing API for SharedTree implemented by this Kernel.
+	 * @remarks
+	 * This is the API grafted onto the ISharedObject which apps can access.
+	 * It includes both the APIs used for internal testing, and public facing APIs (both stable and unstable).
+	 * Different users will have access to different subsets of this API, see {@link ITree}, {@link ITreeAlpha} and {@link ITreeInternal} which this {@link ITreePrivate} extends.
+	 */
+	public readonly view: SharedTreeKernelView;
+
 	public constructor(
 		breaker: Breakable,
 		sharedObject: IChannelView & IFluidLoadable,
@@ -219,9 +246,14 @@ export class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, Shar
 			idCompressor,
 			options,
 		);
-		const schemaSummarizer = new SchemaSummarizer(schema, options, {
-			getCurrentSeq: lastSequenceNumber,
-		});
+		const schemaCodec = makeSchemaCodec(options, codecVersions.schema);
+		const schemaSummarizer = new SchemaSummarizer(
+			schema,
+			{
+				getCurrentSeq: lastSequenceNumber,
+			},
+			schemaCodec,
+		);
 		const fieldBatchCodec = makeFieldBatchCodec(options, codecVersions.fieldBatch);
 
 		const encoderContext = {
@@ -331,6 +363,14 @@ export class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, Shar
 				}
 			}
 		});
+
+		this.view = {
+			contentSnapshot: () => this.contentSnapshot(),
+			exportSimpleSchema: () => this.exportSimpleSchema(),
+			exportVerbose: () => this.exportVerbose(),
+			viewWith: this.viewWith.bind(this),
+			kernel: this,
+		};
 	}
 
 	public exportVerbose(): VerboseTree | undefined {
@@ -450,6 +490,27 @@ export function exportSimpleSchema(storedSchema: TreeStoredSchema): SimpleTreeSc
 	};
 }
 
+/**
+ * A way to parse schema in the persisted format from {@link extractPersistedSchema}.
+ * @remarks
+ * This behaves identically to {@link ITreeAlpha.exportSimpleSchema},
+ * except that it gets the schema from the caller instead of from an existing tree.
+ *
+ * This can be useful for inspecting the contents of persisted schema,
+ * such as those generated by {@link extractPersistedSchema} for use in testing.
+ * Since that data format is otherwise unspecified,
+ * this provides a way to inspect its contents with documented semantics.
+ * @alpha
+ */
+export function persistedToSimpleSchema(
+	persisted: JsonCompatible,
+	options: ICodecOptions,
+): SimpleTreeSchema {
+	const schemaCodec = makeSchemaCodec(options, SchemaCodecVersion.v1);
+	const stored = schemaCodec.decode(persisted as Format);
+	return exportSimpleSchema(stored);
+}
+
 /**
  * Get a {@link BranchableTree} from a {@link ITree}.
  * @remarks The branch can be used for "version control"-style coordination of edits on the tree.

package/src/shared-tree/{treeApi.ts → tree.ts}

@@ -22,6 +22,56 @@ 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.
+ * @remarks
+ * This type should only be used via the {@link (Tree:variable)} export.
+ * @system @sealed @public
+ */
+export interface Tree extends TreeNodeApi {
+	/**
+	 * Run a {@link RunTransaction | transaction}.
+	 */
+	readonly runTransaction: RunTransaction;
+	/**
+	 * Check if the subtree defined by `node` contains `other`.
+	 *
+	 * @returns true if `other` is an inclusive descendant of `node`, and false otherwise.
+	 * @remarks
+	 * This includes direct and indirect children:
+	 * as long as `node` is an ancestor of `other` (occurs in its parentage chain), this returns true, regardless of the number of levels of the tree between.
+	 *
+	 * `node` is considered to contain itself, so the case where `node === other` returns true.
+	 *
+	 * This is handy when checking if moving `node` into `other` would create a cycle and would thus be invalid.
+	 *
+	 * This check walks the parents of `other` looking for `node`,
+	 * and thus runs in time proportional to the depth of child in the tree.
+	 */
+	contains(node: TreeNode, other: TreeNode): boolean;
+}
+
+/**
+ * The {@link (Tree:interface)} singleton which holds various functions for interacting with {@link TreeNode}s.
+ * @public
+ */
+export const Tree: Tree = {
+	...treeNodeApi,
+
+	runTransaction: createRunTransaction(),
+
+	contains(parent: TreeNode, child: TreeNode): boolean {
+		let toCheck: TreeNode | undefined = child;
+		while (toCheck !== undefined) {
+			if (toCheck === parent) {
+				return true;
+			}
+			toCheck = Tree.parent(toCheck);
+		}
+		return false;
+	},
+};
+
 /**
  * A function which runs a transaction in a SharedTree.
  * @privateRemarks
@@ -46,7 +96,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -67,7 +119,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -93,7 +147,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -115,7 +171,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -138,7 +196,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -155,7 +215,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -179,7 +241,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -204,7 +268,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -233,7 +299,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -259,7 +327,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -286,7 +356,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -310,7 +382,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -326,56 +400,6 @@ export interface RunTransaction {
 	): void;
 }
 
-/**
- * Provides various functions for interacting with {@link TreeNode}s.
- * @remarks
- * This type should only be used via the public `Tree` export.
- * @system @sealed @public
- */
-export interface TreeApi extends TreeNodeApi {
-	/**
-	 * Run a {@link RunTransaction | transaction}.
-	 */
-	readonly runTransaction: RunTransaction;
-	/**
-	 * Check if the subtree defined by `node` contains `other`.
-	 *
-	 * @returns true if `other` is an inclusive descendant of `node`, and false otherwise.
-	 * @remarks
-	 * This includes direct and indirect children:
-	 * as long as `node` is an ancestor of `other` (occurs in its parentage chain), this returns true, regardless of the number of levels of the tree between.
-	 *
-	 * `node` is considered to contain itself, so the case where `node === other` returns true.
-	 *
-	 * This is handy when checking if moving `node` into `other` would create a cycle and thus is invalid.
-	 *
-	 * This check walks the parents of `other` looking for `node`,
-	 * and thus runs in time proportional to the depth of child in the tree.
-	 */
-	contains(node: TreeNode, other: TreeNode): boolean;
-}
-
-/**
- * The `Tree` object holds various functions for interacting with {@link TreeNode}s.
- * @public
- */
-export const treeApi: TreeApi = {
-	...treeNodeApi,
-
-	runTransaction: createRunTransaction(),
-
-	contains(parent: TreeNode, child: TreeNode): boolean {
-		let toCheck: TreeNode | undefined = child;
-		while (toCheck !== undefined) {
-			if (toCheck === parent) {
-				return true;
-			}
-			toCheck = treeApi.parent(toCheck);
-		}
-		return false;
-	},
-};
-
 // TODO: Add more constraint types here
 
 /** Creates a copy of `runTransaction` with the `rollback` property added so as to satisfy the `RunTransaction` interface. */
@@ -443,7 +467,7 @@ function runTransactionInCheckout<TResult>(
 		switch (constraint.type) {
 			case "nodeInDocument": {
 				const node = getOrCreateInnerNode(constraint.node);
-				const nodeStatus = treeApi.status(constraint.node);
+				const nodeStatus = Tree.status(constraint.node);
 				if (nodeStatus !== TreeStatus.InDocument) {
 					throw new UsageError(
 						`Attempted to add a "nodeInDocument" constraint, but the node is not currently in the document. Node status: ${nodeStatus}`,