@fluidframework/tree 2.70.0-361092 → 2.70.0-361788

package/src/feature-libraries/incrementalSummarizationUtils.ts

@@ -13,7 +13,7 @@ export interface CollabWindow {
 	 * gives the sequenceNumber of the op currently being processed.
 	 * `undefined` if no message has been processed, e.g. for a detached document or document loaded
 	 * from summary without any subsequent ops.
-	 * @remarks - Most rebasing is built atop a revision system decoupled from message sequence number.
+	 * @remarks Most rebasing is built atop a revision system decoupled from message sequence number.
 	 * However, this is sometimes necessary to interop with Fluid runtime APIs, e.g. for incremental summarization.
 	 */
 	getCurrentSeq: () => number | undefined;

package/src/feature-libraries/index.ts

@@ -110,6 +110,7 @@ export {
 	fluidVersionToFieldBatchCodecWriteVersion,
 	type FieldBatchEncodingContext,
 	emptyChunk,
+	combineChunks,
 	type IncrementalEncodingPolicy,
 	defaultIncrementalEncodingPolicy,
 } from "./chunked-forest/index.js";

package/src/feature-libraries/modular-schema/modularChangeFamily.ts

@@ -2142,7 +2142,7 @@ function deltaFromNodeChange(
  * For example, when rebasing change B from a local branch [A, B, C] over a branch [X, Y], the `baseRevisions` must include
  * revisions [A⁻¹ X, Y, A] if rebasing over the composition of all those changes, or
  * revision [A⁻¹] for the first rebase, then [X], etc. if rebasing over edits individually.
- * @returns - RebaseRevisionMetadata to be passed to `FieldChangeRebaser.rebase`*
+ * @returns RebaseRevisionMetadata to be passed to `FieldChangeRebaser.rebase`*
  */
 export function rebaseRevisionMetadataFromInfo(
 	revInfos: readonly RevisionInfo[],

package/src/feature-libraries/object-forest/objectForest.ts

@@ -49,7 +49,7 @@ import {
 	type Breakable,
 	type WithBreakable,
 } from "../../util/index.js";
-import { chunkFieldSingle, defaultChunkPolicy } from "../chunked-forest/index.js";
+import { chunkField, defaultChunkPolicy } from "../chunked-forest/index.js";
 import { cursorForMapTreeNode, mapTreeFromCursor } from "../mapTreeCursor.js";
 import { type CursorWithNode, SynchronousCursor } from "../treeCursorUtils.js";
 import {
@@ -128,8 +128,8 @@ export class ObjectForest implements IEditableForest, WithBreakable {
 		return new ObjectForest(this.breaker, schema, anchors, this.additionalAsserts, this.roots);
 	}
 
-	public chunkField(cursor: ITreeCursorSynchronous): TreeChunk {
-		return chunkFieldSingle(cursor, { idCompressor: undefined, policy: defaultChunkPolicy });
+	public chunkField(cursor: ITreeCursorSynchronous): TreeChunk[] {
+		return chunkField(cursor, { idCompressor: undefined, policy: defaultChunkPolicy });
 	}
 
 	public forgetAnchor(anchor: Anchor): void {

package/src/feature-libraries/sequence-field/formatV1.ts

@@ -161,7 +161,7 @@ export const Changeset = <Schema extends TSchema>(tNodeChange: Schema) =>
 	Type.Array(Mark(tNodeChange));
 
 /**
- * @privateRemarks - Many of these names are currently used in the sequence-field types. Putting them in a namespace makes codec code more readable.
+ * @privateRemarks Many of these names are currently used in the sequence-field types. Putting them in a namespace makes codec code more readable.
  */
 export namespace Encoded {
 	export type CellCount = Static<typeof CellCount>;

package/src/feature-libraries/sequence-field/formatV2.ts

@@ -110,7 +110,7 @@ export const Changeset = <Schema extends TSchema>(tNodeChange: Schema) =>
 	Type.Array(Mark(tNodeChange));
 
 /**
- * @privateRemarks - Many of these names are currently used in the sequence-field types. Putting them in a namespace makes codec code more readable.
+ * @privateRemarks Many of these names are currently used in the sequence-field types. Putting them in a namespace makes codec code more readable.
  */
 export namespace Encoded {
 	export type CellCount = Static<typeof CellCount>;

package/src/feature-libraries/sequence-field/formatV3.ts

@@ -39,7 +39,7 @@ export const Changeset = <Schema extends TSchema>(tNodeChange: Schema) =>
 	Type.Array(Mark(tNodeChange));
 
 /**
- * @privateRemarks - Many of these names are currently used in the sequence-field types. Putting them in a namespace makes codec code more readable.
+ * @privateRemarks Many of these names are currently used in the sequence-field types. Putting them in a namespace makes codec code more readable.
  */
 export namespace Encoded {
 	export type CellCount = EncodedV2.CellCount;

package/src/index.ts

@@ -123,6 +123,7 @@ export {
 	type WithType,
 	type NodeChangedData,
 	type SchemaUpgrade,
+	contentSchemaSymbol,
 	// Types not really intended for public use, but used in links.
 	// Can not be moved to internalTypes since doing so causes app code to throw errors like:
 	// Error: src/simple-tree/objectNode.ts:72:1 - (ae-unresolved-link) The @link reference could not be resolved: The package "@fluidframework/tree" does not have an export "TreeNodeApi"
@@ -164,6 +165,7 @@ export {
 	singletonSchema,
 	type UnsafeUnknownSchema,
 	type TreeViewAlpha,
+	type TreeViewBeta,
 	type InsertableField,
 	type Insertable,
 	type InsertableContent,
@@ -234,6 +236,7 @@ export {
 	type InsertableTreeNodeFromAllowedTypes,
 	type Input,
 	type TreeBranch,
+	type TreeBranchAlpha,
 	type TreeBranchEvents,
 	asTreeViewAlpha,
 	type NodeSchemaOptions,
@@ -337,4 +340,4 @@ export type { MapNodeInsertableData } from "./simple-tree/index.js";
 export { JsonAsTree } from "./jsonDomainSchema.js";
 export { FluidSerializableAsTree } from "./serializableDomainSchema.js";
 export { TableSchema, type System_TableSchema } from "./tableSchema.js";
-export { asAlpha } from "./api.js";
+export { asAlpha, asBeta } from "./api.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.70.0-361092";
+export const pkgVersion = "2.70.0-361788";

package/src/shared-tree/independentView.ts

@@ -44,6 +44,7 @@ import {
 import { createTreeCheckout } from "./treeCheckout.js";
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import { initialize, initializerFromChunk } from "./schematizeTree.js";
+import { combineChunks } from "../feature-libraries/index.js";
 
 /**
  * Create an uninitialized {@link TreeView} that is not tied to any {@link ITree} instance.
@@ -158,7 +159,9 @@ export function independentInitializedViewInternal<const TSchema extends Implici
 	initialize(
 		checkout,
 		schema,
-		initializerFromChunk(checkout, () => checkout.forest.chunkField(rootFieldCursor)),
+		initializerFromChunk(checkout, () =>
+			combineChunks(checkout.forest.chunkField(rootFieldCursor)),
+		),
 	);
 	return new SchematizingSimpleTreeView<TSchema>(
 		checkout,

package/src/shared-tree/schematizingTreeView.ts

@@ -19,6 +19,7 @@ import {
 	cursorForMapTreeField,
 	TreeStatus,
 	Context,
+	combineChunks,
 	type FlexTreeOptionalField,
 	type FlexTreeUnknownUnboxed,
 	FieldKinds,
@@ -70,6 +71,7 @@ import {
 
 import { canInitialize, initialize, initializerFromChunk } from "./schematizeTree.js";
 import type { ITreeCheckout, TreeCheckout } from "./treeCheckout.js";
+import type { TreeBranchAlpha } from "../simple-tree/index.js";
 
 /**
  * Creating multiple tree views from the same checkout is not supported. This slot is used to detect if one already
@@ -227,8 +229,10 @@ export class SchematizingSimpleTreeView<
 				schema,
 				initializerFromChunk(this.checkout, () => {
 					// This must be done after initial schema is set!
-					return this.checkout.forest.chunkField(
-						cursorForMapTreeField(mapTree === undefined ? [] : [mapTree]),
+					return combineChunks(
+						this.checkout.forest.chunkField(
+							cursorForMapTreeField(mapTree === undefined ? [] : [mapTree]),
+						),
 					);
 				}),
 			);
@@ -510,15 +514,16 @@ export class SchematizingSimpleTreeView<
 
 	// #region Branching
 
-	public fork(): ReturnType<TreeBranch["fork"]> & SchematizingSimpleTreeView<TRootSchema> {
+	public fork(): ReturnType<TreeBranchAlpha["fork"]> &
+		SchematizingSimpleTreeView<TRootSchema> {
 		return this.checkout.branch().viewWith(this.config);
 	}
 
-	public merge(context: TreeBranch, disposeMerged = true): void {
+	public merge(context: TreeBranchAlpha, disposeMerged = true): void {
 		this.checkout.merge(getCheckout(context), disposeMerged);
 	}
 
-	public rebaseOnto(context: TreeBranch): void {
+	public rebaseOnto(context: TreeBranchAlpha): void {
 		getCheckout(context).rebase(this.checkout);
 	}
 

package/src/shared-tree/sharedTree.ts

@@ -667,7 +667,7 @@ export const SharedTreeFormatVersion = {
 	/**
 	 * Requires \@fluidframework/tree \>= 2.0.0.
 	 *
-	 * @deprecated - FF does not currently plan on supporting this format long-term.
+	 * @deprecated FF does not currently plan on supporting this format long-term.
 	 * Do not write production documents using this format, as they may not be loadable in the future.
 	 */
 	v1: 1,

package/src/shared-tree/treeAlpha.ts

@@ -58,6 +58,8 @@ import {
 	importConcise,
 	exportConcise,
 	borrowCursorFromTreeNodeOrValue,
+	contentSchemaSymbol,
+	type TreeNodeSchema,
 } from "../simple-tree/index.js";
 import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import {
@@ -83,8 +85,10 @@ import {
 	type Observer,
 	withObservation,
 } from "../feature-libraries/index.js";
+import type { TreeBranchAlpha } from "../simple-tree/index.js";
 import { independentInitializedView, type ViewContent } from "./independentView.js";
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
+import { isFluidHandle } from "@fluidframework/runtime-utils";
 
 const identifier: TreeIdentifierUtils = (node: TreeNode): string | undefined => {
 	const nodeIdentifier = getIdentifierFromNode(node, "uncompressed");
@@ -227,7 +231,7 @@ export interface TreeAlpha {
 	 * This does not fork a new branch, but rather retrieves the _existing_ branch for the node.
 	 * To create a new branch, use e.g. {@link TreeBranch.fork | `myBranch.fork()`}.
 	 */
-	branch(node: TreeNode): TreeBranch | undefined;
+	branch(node: TreeNode): TreeBranchAlpha | undefined;
 
 	/**
 	 * Construct tree content that is compatible with the field defined by the provided `schema`.
@@ -519,6 +523,35 @@ export interface TreeAlpha {
 		onInvalidation: () => void,
 		trackDuring: () => TResult,
 	): ObservationResults<TResult>;
+
+	/**
+	 * Ensures that the provided content will be interpreted as the given schema when inserting into the tree.
+	 * @returns `content`, for convenience.
+	 * @remarks
+	 * If applicable, this will tag the given content with a {@link contentSchemaSymbol | special property} that indicates its intended schema.
+	 * The `content` will be interpreted as the given `schema` when later inserted into the tree.
+	 *
+	 * This does not validate that the content actually conforms to the given schema (such validation will be done at insert time).
+	 * If the content is not compatible with the tagged schema, an error will be thrown when the content is inserted.
+	 *
+	 * This is particularly useful when the content's schema cannot be inferred from its structure alone because it is compatible with multiple schemas.
+	 * @example
+	 * ```typescript
+	 * const sf = new SchemaFactory("example");
+	 * class Dog extends sf.object("Dog", { name: sf.string() }) {}
+	 * class Cat extends sf.object("Cat", { name: sf.string() }) {}
+	 * class Root extends sf.object("Root", { pet: [Dog, Cat] }) {}
+	 * // ...
+	 * const pet = { name: "Max" };
+	 * view.root.pet = pet; // Error: ambiguous schema - is it a Dog or a Cat?
+	 * TreeAlpha.ensureSchema(Dog, pet); // Tags `pet` as a Dog.
+	 * view.root.pet = pet; // No error - it's a Dog.
+	 * ```
+	 */
+	tagContentSchema<TSchema extends TreeNodeSchema, TContent extends InsertableField<TSchema>>(
+		schema: TSchema,
+		content: TContent,
+	): TContent;
 }
 
 /**
@@ -723,7 +756,7 @@ export const TreeAlpha: TreeAlpha = {
 		return result;
 	},
 
-	branch(node: TreeNode): TreeBranch | undefined {
+	branch(node: TreeNode): TreeBranchAlpha | undefined {
 		const kernel = getKernel(node);
 		if (!kernel.isHydrated()) {
 			return undefined;
@@ -1003,6 +1036,21 @@ export const TreeAlpha: TreeAlpha = {
 		}
 		return result;
 	},
+
+	tagContentSchema<TSchema extends TreeNodeSchema, TNode extends InsertableField<TSchema>>(
+		schema: TSchema,
+		node: TNode,
+	): TNode {
+		if (typeof node === "object" && node !== null && !isFluidHandle(node)) {
+			Reflect.defineProperty(node, contentSchemaSymbol, {
+				configurable: false,
+				enumerable: false,
+				writable: true,
+				value: schema.identifier,
+			});
+		}
+		return node;
+	},
 };
 
 /**

package/src/shared-tree/treeCheckout.ts

@@ -636,7 +636,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	 * @param kind - The {@link CommitKind} that produced this revertible (e.g., Default, Undo, Redo).
 	 * @param checkout - The {@link TreeCheckout} instance this revertible belongs to.
 	 * @param onRevertibleDisposed - Callback function that will be called when the revertible is disposed.
-	 * @returns - {@link RevertibleAlpha}
+	 * @returns A {@link RevertibleAlpha} object.
 	 */
 	private createRevertible(
 		revision: RevisionTag,

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

@@ -719,7 +719,7 @@ function scopeStorageService(
 			return service.list(`${scope}${path}`);
 		},
 		getSnapshotTree(): ISnapshotTree | undefined {
-			const snapshotTree = service.getSnapshotTree?.();
+			const snapshotTree = service.getSnapshotTree();
 			if (snapshotTree === undefined) {
 				return undefined;
 			}

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

@@ -42,7 +42,7 @@ export interface Transactor {
 	 * If a transaction is already in progress when this new transaction starts, then this transaction will be "nested" inside of it,
 	 * i.e. the outer transaction will still be in progress after this new transaction is committed or aborted.
 	 *
-	 * @remarks - Asynchronous transactions are not supported on the root checkout,
+	 * @remarks Asynchronous transactions are not supported on the root checkout,
 	 * since it is always kept up-to-date with the latest remote edits and the results of this rebasing (which might invalidate
 	 * the transaction) is not visible to the application author.
 	 * Instead,
@@ -51,7 +51,7 @@ export interface Transactor {
 	 * 2. run the transaction on the fork
 	 * 3. merge the fork back into the root checkout
 	 *
-	 * @privateRemarks - There is currently no enforcement that asynchronous transactions don't happen on the root checkout.
+	 * @privateRemarks There is currently no enforcement that asynchronous transactions don't happen on the root checkout.
 	 * AB#6488 tracks adding some enforcement to make it more clear to application authors that this is not supported.
 	 */
 	start(): void;

package/src/simple-tree/api/incrementalAllowedTypes.ts

@@ -0,0 +1,107 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { FieldKey, TreeNodeSchemaIdentifier } from "../../core/index.js";
+import { getTreeNodeSchemaPrivateData, type AllowedTypesFull } from "../core/index.js";
+import { isObjectNodeSchema } from "../node-kinds/index.js";
+import type { TreeSchema } from "./configuration.js";
+import type { IncrementalEncodingPolicy } from "../../feature-libraries/index.js";
+import { oneFromIterable } from "../../util/index.js";
+import { assert } from "@fluidframework/core-utils/internal";
+
+/**
+ * A symbol when present in the {@link AnnotatedAllowedTypes.metadata.custom} property as true, opts in the allowed
+ * types to incremental summary optimization.
+ * These allowed types will be optimized during summary such that if they don't change across summaries,
+ * they will not be encoded and their content will not be included in the summary that is uploaded to the service.
+ * @remarks
+ * See {@link getShouldIncrementallySummarizeAllowedTypes} for more details.
+ *
+ * Use {@link SchemaStaticsAlpha.types} to add this metadata to allowed types in a schema.
+ * @example
+ * ```typescript
+ * const sf = new SchemaFactoryAlpha("IncrementalSummarization");
+ * class Foo extends sf.objectAlpha("foo", {
+ *   bar: sf.types([{ type: sf.string, metadata: {} }], {
+ *     custom: { [incrementalSummaryHint]: true },
+ *   }),
+ * }) {}
+ * ```
+ */
+export const incrementalSummaryHint: unique symbol = Symbol("IncrementalSummaryHint");
+
+/**
+ * Returns true if the provided allowed types's custom metadata has {@link incrementalSummaryHint} as true.
+ */
+function isIncrementalSummaryHintInAllowedTypes(allowedTypes: AllowedTypesFull): boolean {
+	const customMetadata = allowedTypes.metadata.custom;
+	return (
+		customMetadata !== undefined &&
+		(customMetadata as Record<symbol, unknown>)[incrementalSummaryHint] === true
+	);
+}
+
+/**
+ * This helper function {@link getShouldIncrementallySummarizeAllowedTypes} can be used to generate a callback function
+ * of type {@link IncrementalEncodingPolicy}.
+ * This callback can be passed as the value for {@link SharedTreeOptionsInternal.shouldEncodeFieldIncrementally} parameter
+ * when creating the tree.
+ * It will be called for each {@link AllowedTypes} in the schema to determine if it should be incrementally summarized.
+ *
+ * @param rootSchema - The schema for the root of the tree.
+ * @returns A callback function of type {@link IncrementalEncodingPolicy} which can be used to determine if a field
+ * should be incrementally summarized based on whether it is an allowed types with the
+ * {@link incrementalAllowedTypesMetadata} metadata.
+ *
+ * @remarks
+ * This only works for forest type {@link ForestTypeOptimized} and compression strategy
+ * {@link TreeCompressionStrategyExtended.CompressedIncremental}.
+ *
+ * The {@link incrementalAllowedTypesMetadata} will be replaced with a specialized metadata property once the
+ * incremental summary feature and APIs are stabilized.
+ */
+export function getShouldIncrementallySummarizeAllowedTypes(
+	rootSchema: TreeSchema,
+): IncrementalEncodingPolicy {
+	return (
+		targetNodeIdentifier: TreeNodeSchemaIdentifier | undefined,
+		targetFieldKey: FieldKey,
+	) => {
+		if (targetNodeIdentifier === undefined) {
+			// Root fields cannot be allowed types, so we don't incrementally summarize them.
+			return false;
+		}
+
+		const targetNode = rootSchema.definitions.get(targetNodeIdentifier);
+		if (targetNode === undefined) {
+			// The requested type is unknown to this schema.
+			// In this case we have no hints available from the view schema, and fall back to the default behavior of non-incremental encoding.
+			// There are two ways this can happen:
+			// 1. The view schema being used does not match the stored schema.
+			// 2. The view schema is compatible, but there are unknown optional fields which contain new types not described by the view schema.
+			return false;
+		}
+
+		if (isObjectNodeSchema(targetNode)) {
+			const targetPropertyKey = targetNode.storedKeyToPropertyKey.get(targetFieldKey);
+			if (targetPropertyKey !== undefined) {
+				const fieldSchema = targetNode.fields.get(targetPropertyKey);
+				if (fieldSchema !== undefined) {
+					return isIncrementalSummaryHintInAllowedTypes(fieldSchema.allowedTypesFull);
+				}
+			}
+			return false;
+		}
+
+		const allowedTypes = oneFromIterable(
+			getTreeNodeSchemaPrivateData(targetNode).childAllowedTypes,
+		);
+		assert(
+			allowedTypes !== undefined,
+			"Non object nodes with fields should only have one allowedTypes entry",
+		);
+		return isIncrementalSummaryHintInAllowedTypes(allowedTypes);
+	};
+}

package/src/simple-tree/api/index.ts

@@ -19,7 +19,9 @@ export type {
 	TreeViewEvents,
 	SchemaCompatibilityStatus,
 	TreeViewAlpha,
+	TreeViewBeta,
 	TreeBranch,
+	TreeBranchAlpha,
 	TreeBranchEvents,
 	ITreeAlpha,
 } from "./tree.js";
@@ -161,3 +163,7 @@ export {
 export { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
 export { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 export type { TreeChangeEvents } from "./treeChangeEvents.js";
+export {
+	getShouldIncrementallySummarizeAllowedTypes,
+	incrementalSummaryHint,
+} from "./incrementalAllowedTypes.js";

package/src/simple-tree/api/schemaFactoryBeta.ts

@@ -88,7 +88,9 @@ export class SchemaFactoryBeta<
 		TreeObjectNode<T, ScopedSchemaName<TScope, Name>>,
 		object & InsertableObjectFromSchemaRecord<T>,
 		true,
-		T
+		T,
+		never,
+		TCustomMetadata
 	> {
 		return objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {
 			...defaultSchemaFactoryObjectOptions,
@@ -110,7 +112,9 @@ export class SchemaFactoryBeta<
 		System_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,
 		object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,
 		false,
-		T
+		T,
+		never,
+		TCustomMetadata
 	> {
 		type TScopedName = ScopedSchemaName<TScope, Name>;
 		return this.object(

package/src/simple-tree/api/tree.ts

@@ -126,37 +126,10 @@ export interface ITreeAlpha extends ITree {
  * A collection of functionality associated with a (version-control-style) branch of a SharedTree.
  * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork | creation of branches} and for those branches to later be {@link TreeBranch.merge | merged}.
  *
- * The `TreeBranch` for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.branch`.
- *
- * A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha | view with a schema}, use {@link TreeBranch.hasRootSchema | hasRootSchema()}.
- *
  * The branch associated directly with the {@link ITree | SharedTree} is the "main" branch, and all other branches fork (directly or transitively) from that main branch.
- * @sealed @alpha
+ * @sealed @beta
  */
 export interface TreeBranch extends IDisposable {
-	/**
-	 * Events for the branch
-	 */
-	readonly events: Listenable<TreeBranchEvents>;
-
-	/**
-	 * Returns true if this branch has the given schema as its root schema.
-	 * @remarks This is a type guard which allows this branch to become strongly typed as a {@link TreeViewAlpha | view} of the given schema.
-	 *
-	 * To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types.
-	 * For example, a schema of `Foo | Bar` will not match a view schema of `Foo`, and likewise a schema of `Foo` will not match a view schema of `Foo | Bar`.
-	 * @example
-	 * ```typescript
-	 * if (branch.hasRootSchema(MySchema)) {
-	 *   const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>
-	 *   // ...
-	 * }
-	 * ```
-	 */
-	hasRootSchema<TSchema extends ImplicitFieldSchema>(
-		schema: TSchema,
-	): this is TreeViewAlpha<TSchema>;
-
 	/**
 	 * Fork a new branch off of this branch which is based off of this branch's current state.
 	 * @remarks Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. {@link TreeBranch.merge | merged} back into this branch.
@@ -187,6 +160,54 @@ export interface TreeBranch extends IDisposable {
 	 */
 	rebaseOnto(branch: TreeBranch): void;
 
+	/**
+	 * Dispose of this branch, cleaning up any resources associated with it.
+	 * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.
+	 * @remarks Branches can also be automatically disposed when {@link TreeBranch.merge | they are merged} into another branch.
+	 *
+	 * Disposing branches is important to avoid consuming memory unnecessarily.
+	 * In particular, the SharedTree retains all sequenced changes made to the tree since the "most-behind" branch was created or last {@link TreeBranch.rebaseOnto | rebased}.
+	 *
+	 * The {@link TreeBranch | main branch} cannot be disposed - attempting to do so will have no effect.
+	 */
+	dispose(error?: Error): void;
+}
+
+/**
+ * {@link TreeBranch} with alpha-level APIs.
+ * @remarks
+ * The `TreeBranch` for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.branch`.
+ *
+ * A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha | view with a schema}, use {@link TreeBranchAlpha.hasRootSchema | hasRootSchema()}.
+ * @sealed @alpha
+ */
+export interface TreeBranchAlpha extends TreeBranch {
+	/**
+	 * Events for the branch
+	 */
+	readonly events: Listenable<TreeBranchEvents>;
+
+	/**
+	 * Returns true if this branch has the given schema as its root schema.
+	 * @remarks This is a type guard which allows this branch to become strongly typed as a {@link TreeViewAlpha | view} of the given schema.
+	 *
+	 * To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types.
+	 * For example, a schema of `Foo | Bar` will not match a view schema of `Foo`, and likewise a schema of `Foo` will not match a view schema of `Foo | Bar`.
+	 * @example
+	 * ```typescript
+	 * if (branch.hasRootSchema(MySchema)) {
+	 *   const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>
+	 *   // ...
+	 * }
+	 * ```
+	 */
+	hasRootSchema<TSchema extends ImplicitFieldSchema>(
+		schema: TSchema,
+	): this is TreeViewAlpha<TSchema>;
+
+	// Override the base fork method to return the alpha variant.
+	fork(): TreeBranchAlpha;
+
 	/**
 	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
 	 * @param transaction - The function to run as the body of the transaction.
@@ -261,18 +282,6 @@ export interface TreeBranch extends IDisposable {
 		transaction: () => VoidTransactionCallbackStatus | void,
 		params?: RunTransactionParams,
 	): TransactionResult;
-
-	/**
-	 * Dispose of this branch, cleaning up any resources associated with it.
-	 * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.
-	 * @remarks Branches can also be automatically disposed when {@link TreeBranch.merge | they are merged} into another branch.
-	 *
-	 * Disposing branches is important to avoid consuming memory unnecessarily.
-	 * In particular, the SharedTree retains all sequenced changes made to the tree since the "most-behind" branch was created or last {@link TreeBranch.rebaseOnto | rebased}.
-	 *
-	 * The {@link TreeBranch | main branch} cannot be disposed - attempting to do so will have no effect.
-	 */
-	dispose(error?: Error): void;
 }
 
 /**
@@ -371,18 +380,29 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
  */
 export interface TreeViewAlpha<
 	in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
-> extends Omit<TreeView<ReadSchema<TSchema>>, "root" | "initialize">,
-		TreeBranch {
+> extends Omit<TreeViewBeta<ReadSchema<TSchema>>, "root" | "initialize" | "fork">,
+		TreeBranchAlpha {
 	get root(): ReadableField<TSchema>;
 
 	set root(newRoot: InsertableField<TSchema>);
 
+	initialize(content: InsertableField<TSchema>): void;
+
 	readonly events: Listenable<TreeViewEvents & TreeBranchEvents>;
 
-	initialize(content: InsertableField<TSchema>): void;
+	// Override the base fork method to return a TreeViewAlpha.
+	fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>;
+}
 
+/**
+ * {@link TreeView} with additional beta APIs.
+ * @sealed @beta
+ */
+export interface TreeViewBeta<in out TSchema extends ImplicitFieldSchema>
+	extends TreeView<TSchema>,
+		TreeBranch {
 	// Override the base branch method to return a typed view rather than merely a branch.
-	fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>;
+	fork(): ReturnType<TreeBranch["fork"]> & TreeViewBeta<TSchema>;
 }
 
 /**