Promote minimal SharedTree branch APIs to beta (#25744)

## Description

This PR promotes the minimal set of APIs necessary to enable local
branching flows in SharedTree.

---------

Co-authored-by: Abram Sanderson <absander@microsoft.com>

Author: Abe27342

.changeset/crazy-carrots-mate.md

@@ -0,0 +1,17 @@
+---
+"fluid-framework": minor
+"@fluidframework/tree": minor
+"@fluidframework/tree-agent": minor
+"__section": feature
+---
+A minimal set of branching APIs has been promoted to beta.
+
+The following APIs have been promoted to beta in `@fluidframework/tree`:
+
+- `TreeBranch.fork()`
+- `TreeBranch.merge()`
+- `TreeBranch.rebaseOnto()`
+- `TreeBranch.dispose()`
+- `TreeView.fork()`
+
+These APIs enable applications to implement basic local branching flows.

packages/dds/tree/api-report/tree.alpha.api.md

@@ -117,6 +117,9 @@ export const ArrayNodeSchema: {
 // @alpha
 export function asAlpha<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewAlpha<TSchema>;
 
+// @beta
+export function asBeta<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewBeta<TSchema>;
+
 // @alpha @deprecated
 export function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewAlpha<TSchema>;
 
@@ -1347,7 +1350,7 @@ export const Tree: Tree;
 
 // @alpha @sealed @system
 export interface TreeAlpha {
-    branch(node: TreeNode): TreeBranch | undefined;
+    branch(node: TreeNode): TreeBranchAlpha | undefined;
     child(node: TreeNode, key: string | number): TreeNode | TreeLeafValue | undefined;
     children(node: TreeNode): Iterable<[propertyKey: string | number, child: TreeNode | TreeLeafValue]>;
     create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: InsertableField<TSchema>): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;
@@ -1412,14 +1415,20 @@ export interface TreeBeta {
 // @beta
 export const TreeBeta: TreeBeta;
 
-// @alpha @sealed
+// @beta @sealed
 export interface TreeBranch extends IDisposable {
     dispose(error?: Error): void;
-    readonly events: Listenable_2<TreeBranchEvents>;
     fork(): TreeBranch;
-    hasRootSchema<TSchema extends ImplicitFieldSchema>(schema: TSchema): this is TreeViewAlpha<TSchema>;
     merge(branch: TreeBranch, disposeMerged?: boolean): void;
     rebaseOnto(branch: TreeBranch): void;
+}
+
+// @alpha @sealed
+export interface TreeBranchAlpha extends TreeBranch {
+    readonly events: Listenable_2<TreeBranchEvents>;
+    // (undocumented)
+    fork(): TreeBranchAlpha;
+    hasRootSchema<TSchema extends ImplicitFieldSchema>(schema: TSchema): this is TreeViewAlpha<TSchema>;
     runTransaction<TSuccessValue, TFailureValue>(transaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>, params?: RunTransactionParams): TransactionResultExt<TSuccessValue, TFailureValue>;
     runTransaction(transaction: () => VoidTransactionCallbackStatus | void, params?: RunTransactionParams): TransactionResult;
 }
@@ -1599,7 +1608,7 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
 }
 
 // @alpha @sealed
-export interface TreeViewAlpha<in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema> extends Omit<TreeView<ReadSchema<TSchema>>, "root" | "initialize">, TreeBranch {
+export interface TreeViewAlpha<in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema> extends Omit<TreeViewBeta<ReadSchema<TSchema>>, "root" | "initialize" | "fork">, TreeBranchAlpha {
     // (undocumented)
     readonly events: Listenable_2<TreeViewEvents & TreeBranchEvents>;
     // (undocumented)
@@ -1611,6 +1620,12 @@ export interface TreeViewAlpha<in out TSchema extends ImplicitFieldSchema | Unsa
     set root(newRoot: InsertableField<TSchema>);
 }
 
+// @beta @sealed
+export interface TreeViewBeta<in out TSchema extends ImplicitFieldSchema> extends TreeView<TSchema>, TreeBranch {
+    // (undocumented)
+    fork(): ReturnType<TreeBranch["fork"]> & TreeViewBeta<TSchema>;
+}
+
 // @public @sealed
 export class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> implements Required<ITreeViewConfiguration<TSchema>> {
     constructor(props: ITreeViewConfiguration<TSchema>);

packages/dds/tree/api-report/tree.beta.api.md

@@ -70,6 +70,9 @@ type ApplyKindInput<T, Kind extends FieldKind, DefaultsAreOptional extends boole
 Kind
 ] extends [FieldKind.Required] ? T : [Kind] extends [FieldKind.Optional] ? T | undefined : [Kind] extends [FieldKind.Identifier] ? DefaultsAreOptional extends true ? T | undefined : T : never;
 
+// @beta
+export function asBeta<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewBeta<TSchema>;
+
 // @public
 export enum CommitKind {
     Default = 0,
@@ -672,6 +675,14 @@ export interface TreeBeta {
 // @beta
 export const TreeBeta: TreeBeta;
 
+// @beta @sealed
+export interface TreeBranch extends IDisposable {
+    dispose(error?: Error): void;
+    fork(): TreeBranch;
+    merge(branch: TreeBranch, disposeMerged?: boolean): void;
+    rebaseOnto(branch: TreeBranch): void;
+}
+
 // @public @sealed
 export interface TreeChangeEvents {
     nodeChanged(unstable?: unknown): void;
@@ -795,6 +806,12 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
     upgradeSchema(): void;
 }
 
+// @beta @sealed
+export interface TreeViewBeta<in out TSchema extends ImplicitFieldSchema> extends TreeView<TSchema>, TreeBranch {
+    // (undocumented)
+    fork(): ReturnType<TreeBranch["fork"]> & TreeViewBeta<TSchema>;
+}
+
 // @public @sealed
 export class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> implements Required<ITreeViewConfiguration<TSchema>> {
     constructor(props: ITreeViewConfiguration<TSchema>);

packages/dds/tree/api-report/tree.legacy.beta.api.md

@@ -70,6 +70,9 @@ type ApplyKindInput<T, Kind extends FieldKind, DefaultsAreOptional extends boole
 Kind
 ] extends [FieldKind.Required] ? T : [Kind] extends [FieldKind.Optional] ? T | undefined : [Kind] extends [FieldKind.Identifier] ? DefaultsAreOptional extends true ? T | undefined : T : never;
 
+// @beta
+export function asBeta<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewBeta<TSchema>;
+
 // @public
 export enum CommitKind {
     Default = 0,
@@ -684,6 +687,14 @@ export interface TreeBeta {
 // @beta
 export const TreeBeta: TreeBeta;
 
+// @beta @sealed
+export interface TreeBranch extends IDisposable {
+    dispose(error?: Error): void;
+    fork(): TreeBranch;
+    merge(branch: TreeBranch, disposeMerged?: boolean): void;
+    rebaseOnto(branch: TreeBranch): void;
+}
+
 // @public @sealed
 export interface TreeChangeEvents {
     nodeChanged(unstable?: unknown): void;
@@ -807,6 +818,12 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
     upgradeSchema(): void;
 }
 
+// @beta @sealed
+export interface TreeViewBeta<in out TSchema extends ImplicitFieldSchema> extends TreeView<TSchema>, TreeBranch {
+    // (undocumented)
+    fork(): ReturnType<TreeBranch["fork"]> & TreeViewBeta<TSchema>;
+}
+
 // @public @sealed
 export class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> implements Required<ITreeViewConfiguration<TSchema>> {
     constructor(props: ITreeViewConfiguration<TSchema>);

packages/dds/tree/src/api.ts

@@ -6,6 +6,7 @@
 import {
 	type TreeView,
 	type TreeViewAlpha,
+	type TreeViewBeta,
 	type ImplicitFieldSchema,
 	// eslint-disable-next-line import/no-deprecated
 	asTreeViewAlpha,
@@ -28,3 +29,13 @@ export function asAlpha<TSchema extends ImplicitFieldSchema>(
 	// eslint-disable-next-line import/no-deprecated
 	return asTreeViewAlpha(view);
 }
+
+/**
+ * Retrieve the {@link TreeViewBeta | beta API} for a {@link TreeView}.
+ * @beta
+ */
+export function asBeta<TSchema extends ImplicitFieldSchema>(
+	view: TreeView<TSchema>,
+): TreeViewBeta<TSchema> {
+	return view as TreeViewBeta<TSchema>;
+}

packages/dds/tree/src/index.ts

@@ -165,6 +165,7 @@ export {
 	singletonSchema,
 	type UnsafeUnknownSchema,
 	type TreeViewAlpha,
+	type TreeViewBeta,
 	type InsertableField,
 	type Insertable,
 	type InsertableContent,
@@ -235,6 +236,7 @@ export {
 	type InsertableTreeNodeFromAllowedTypes,
 	type Input,
 	type TreeBranch,
+	type TreeBranchAlpha,
 	type TreeBranchEvents,
 	asTreeViewAlpha,
 	type NodeSchemaOptions,
@@ -338,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";

packages/dds/tree/src/shared-tree/schematizingTreeView.ts

@@ -71,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
@@ -513,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);
 	}
 

packages/dds/tree/src/shared-tree/treeAlpha.ts

@@ -85,6 +85,7 @@ 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";
@@ -230,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`.
@@ -755,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;

packages/dds/tree/src/simple-tree/api/index.ts

@@ -19,7 +19,9 @@ export type {
 	TreeViewEvents,
 	SchemaCompatibilityStatus,
 	TreeViewAlpha,
+	TreeViewBeta,
 	TreeBranch,
+	TreeBranchAlpha,
 	TreeBranchEvents,
 	ITreeAlpha,
 } from "./tree.js";