@fluidframework/tree 2.61.0 → 2.62.0

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

@@ -4,10 +4,14 @@
  */
 
 import type { IFluidLoadable, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail, unreachableCase } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type { ISnapshotTree } from "@fluidframework/driver-definitions/internal";
-import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
+import type {
+	IIdCompressor,
+	SessionId,
+	SessionSpaceCompressedId,
+} from "@fluidframework/id-compressor";
 import type {
 	IExperimentalIncrementalSummaryContext,
 	IRuntimeMessageCollection,
@@ -42,13 +46,13 @@ import {
 	breakingClass,
 } from "../util/index.js";
 
-import type { SharedTreeBranch } from "./branch.js";
+import type { BranchId, SharedTreeBranch } from "./branch.js";
 import { BranchCommitEnricher } from "./branchCommitEnricher.js";
 import { type ChangeEnricherReadonlyCheckout, NoOpChangeEnricher } from "./changeEnricher.js";
 import { DefaultResubmitMachine } from "./defaultResubmitMachine.js";
 import { EditManager, minimumPossibleSequenceNumber } from "./editManager.js";
 import { makeEditManagerCodec } from "./editManagerCodecs.js";
-import type { SeqNumber } from "./editManagerFormat.js";
+import type { SeqNumber } from "./editManagerFormatCommons.js";
 import { EditManagerSummarizer } from "./editManagerSummarizer.js";
 import { type MessageEncodingContext, makeMessageCodec } from "./messageCodecs.js";
 import type { DecodedMessage } from "./messageTypes.js";
@@ -98,8 +102,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		MessageEncodingContext
 	>;
 
-	private readonly resubmitMachine: ResubmitMachine<TChange>;
-	public readonly commitEnricher: BranchCommitEnricher<TChange>;
+	private readonly enrichers: Map<BranchId, EnricherState<TChange>> = new Map();
 
 	public readonly mintRevisionTag: () => RevisionTag;
 
@@ -120,10 +123,10 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		public readonly submitLocalMessage: (content: unknown, localOpMetadata?: unknown) => void,
 		logger: ITelemetryBaseLogger | undefined,
 		summarizables: readonly Summarizable[],
-		changeFamily: ChangeFamily<TEditor, TChange>,
+		protected readonly changeFamily: ChangeFamily<TEditor, TChange>,
 		options: ICodecOptions,
 		formatOptions: ExplicitCoreCodecVersions,
-		private readonly idCompressor: IIdCompressor,
+		protected readonly idCompressor: IIdCompressor,
 		schema: TreeStoredSchemaRepository,
 		schemaPolicy: SchemaPolicy,
 		resubmitMachine?: ResubmitMachine<TChange>,
@@ -151,20 +154,11 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			changeFamily,
 			localSessionId,
 			this.mintRevisionTag,
+			(branchId) => this.registerSharedBranch(branchId),
 			rebaseLogger,
 		);
 
-		this.editManager.localBranch.events.on("beforeChange", (change) => {
-			if (this.detachedRevision === undefined) {
-				// Commit enrichment is only necessary for changes that will be submitted as ops, and changes issued while detached are not submitted.
-				this.commitEnricher.processChange(change);
-			}
-			if (change.type === "append") {
-				for (const commit of change.newCommits) {
-					this.submitCommit(commit, this.schemaAndPolicy, false);
-				}
-			}
-		});
+		this.registerSharedBranch("main");
 
 		const revisionTagCodec = new RevisionTagCodec(idCompressor);
 		const editManagerCodec = makeEditManagerCodec(
@@ -194,15 +188,11 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			formatOptions.message,
 		);
 
-		const changeEnricher = enricher ?? new NoOpChangeEnricher();
-		this.resubmitMachine =
-			resubmitMachine ??
-			new DefaultResubmitMachine(
-				(change: TaggedChange<TChange>) =>
-					changeFamily.rebaser.invert(change, true, this.mintRevisionTag()),
-				changeEnricher,
-			);
-		this.commitEnricher = new BranchCommitEnricher(changeFamily.rebaser, changeEnricher);
+		this.registerSharedBranchForEditing(
+			"main",
+			enricher ?? new NoOpChangeEnricher(),
+			resubmitMachine,
+		);
 	}
 
 	// TODO: SharedObject's merging of the two summary methods into summarizeCore is not what we want here:
@@ -245,7 +235,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 
 	public async loadCore(services: IChannelStorageService): Promise<void> {
 		assert(
-			this.editManager.localBranch.getHead() === this.editManager.getTrunkHead(),
+			this.getLocalBranch().getHead() === this.editManager.getTrunkHead("main"),
 			0xaaa /* All local changes should be applied to the trunk before loading from summary */,
 		);
 		const [editManagerSummarizer, ...summarizables] = this.summarizables;
@@ -259,8 +249,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			// First, finish loading the edit manager so that we can inspect the sequence numbers of the commits on the trunk.
 			await loadEditManager;
 
-			const head = this.editManager.getTrunkHead();
-			const latestDetachedSequenceNumber = this.editManager.getSequenceNumber(head);
+			const latestDetachedSequenceNumber = this.editManager.getLatestSequenceNumber();
 			// When we load a summary for a tree that was never attached,
 			// latestDetachedSequenceNumber is either undefined (no commits in summary) or negative (all commits in summary were made while detached).
 			// We only need to update `this.detachedRevision` in the latter case.
@@ -273,6 +262,21 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		}
 	}
 
+	private registerSharedBranch(branchId: BranchId): void {
+		this.editManager.getLocalBranch(branchId).events.on("beforeChange", (change) => {
+			if (change.type === "append") {
+				if (this.detachedRevision === undefined) {
+					// Commit enrichment is only necessary for changes that will be submitted as ops, and changes issued while detached are not submitted.
+					this.getCommitEnricher(branchId).processChange(change);
+				}
+
+				for (const commit of change.newCommits) {
+					this.submitCommit(branchId, commit, this.schemaAndPolicy, false);
+				}
+			}
+		});
+	}
+
 	private async loadSummarizable(
 		summarizable: Summarizable,
 		services: IChannelStorageService,
@@ -290,6 +294,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	 * and may differ from `commit` due to enrichments like detached tree refreshers.
 	 */
 	protected submitCommit(
+		branchId: BranchId,
 		commit: GraphCommit<TChange>,
 		schemaAndPolicy: ClonableSchemaAndPolicy,
 		isResubmit: boolean,
@@ -301,7 +306,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 
 		const enrichedCommit =
 			this.detachedRevision === undefined && !isResubmit
-				? this.commitEnricher.enrich(commit)
+				? this.getCommitEnricher(branchId).enrich(commit)
 				: commit;
 
 		// Edits submitted before the first attach are treated as sequenced because they will be included
@@ -315,26 +320,45 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				this.editManager.localSessionId,
 				newRevision,
 				this.detachedRevision,
+				branchId,
 			);
 			this.editManager.advanceMinimumSequenceNumber(newRevision, false);
 			return undefined;
 		}
-		const message = this.messageCodec.encode(
+
+		this.submitMessage(
 			{
+				type: "commit",
 				commit: enrichedCommit,
 				sessionId: this.editManager.localSessionId,
+				branchId,
 			},
-			{
-				idCompressor: this.idCompressor,
-				schema: schemaAndPolicy,
-			},
+			schemaAndPolicy,
+		);
+
+		this.getResubmitMachine(branchId).onCommitSubmitted(enrichedCommit);
+	}
+
+	protected submitBranchCreation(branchId: BranchId): void {
+		this.submitMessage(
+			{ type: "branch", sessionId: this.editManager.localSessionId, branchId },
+			this.schemaAndPolicy,
 		);
-		this.submitLocalMessage(message, {
+	}
+
+	private submitMessage(
+		message: DecodedMessage<TChange>,
+		schemaAndPolicy: ClonableSchemaAndPolicy,
+	): void {
+		const encodedMessage = this.messageCodec.encode(message, {
+			idCompressor: this.idCompressor,
+			schema: schemaAndPolicy,
+		});
+		this.submitLocalMessage(encodedMessage, {
 			// Clone the schema to ensure that during resubmit the schema has not been mutated by later changes
 			schema: schemaAndPolicy.schema.clone(),
 			policy: schemaAndPolicy.policy,
 		});
-		this.resubmitMachine.onCommitSubmitted(enrichedCommit);
 	}
 
 	/**
@@ -344,43 +368,117 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		const { envelope, local, messagesContent } = messagesCollection;
 		const commits: GraphCommit<TChange>[] = [];
 		let messagesSessionId: SessionId | undefined;
+		let branchId: BranchId | undefined;
+
+		const processBunch = (branch: BranchId): void => {
+			assert(messagesSessionId !== undefined, 0xada /* Messages must have a session ID */);
+			this.processCommits(
+				messagesSessionId,
+				brand(envelope.sequenceNumber),
+				brand(envelope.referenceSequenceNumber),
+				local,
+				branch,
+				commits,
+			);
+
+			commits.length = 0;
+			branchId = undefined;
+		};
 
 		// Get a list of all the commits from the messages.
 		for (const messageContent of messagesContent) {
 			// Empty context object is passed in, as our decode function is schema-agnostic.
-			const { commit, sessionId } = this.messageCodec.decode(messageContent.contents, {
+			const message = this.messageCodec.decode(messageContent.contents, {
 				idCompressor: this.idCompressor,
 			});
-			commits.push(commit);
 
 			if (messagesSessionId !== undefined) {
 				assert(
-					messagesSessionId === sessionId,
+					messagesSessionId === message.sessionId,
 					0xad9 /* All messages in a bunch must have the same session ID */,
 				);
 			}
-			messagesSessionId = sessionId;
+			messagesSessionId = message.sessionId;
+
+			const type = message.type;
+			switch (type) {
+				case "commit": {
+					if (branchId !== undefined && message.branchId !== branchId) {
+						processBunch(branchId);
+					}
+
+					branchId = message.branchId;
+					commits.push(message.commit);
+					break;
+				}
+				case "branch": {
+					if (branchId !== undefined) {
+						processBunch(branchId);
+					}
+					this.editManager.sequenceBranchCreation(
+						messagesSessionId,
+						brand(envelope.referenceSequenceNumber),
+						message.branchId,
+					);
+					break;
+				}
+				default:
+					unreachableCase(type);
+			}
 		}
 
-		assert(messagesSessionId !== undefined, 0xada /* Messages must have a session ID */);
+		if (branchId !== undefined) {
+			processBunch(branchId);
+		}
+
+		this.editManager.advanceMinimumSequenceNumber(brand(envelope.minimumSequenceNumber));
+	}
 
+	private processCommits(
+		sessionId: SessionId,
+		sequenceNumber: SeqNumber,
+		referenceSequenceNumber: SeqNumber,
+		isLocal: boolean,
+		branchId: BranchId,
+		commits: readonly GraphCommit<TChange>[],
+	): void {
 		this.editManager.addSequencedChanges(
 			commits,
-			messagesSessionId,
-			brand(envelope.sequenceNumber),
-			brand(envelope.referenceSequenceNumber),
+			sessionId,
+			sequenceNumber,
+			referenceSequenceNumber,
+			branchId,
 		);
 
 		// Update the resubmit machine for each commit applied.
-		for (const _ of messagesContent) {
-			this.resubmitMachine.onSequencedCommitApplied(local);
+		for (const _ of commits) {
+			this.tryGetResubmitMachine(branchId)?.onSequencedCommitApplied(isLocal);
 		}
-
-		this.editManager.advanceMinimumSequenceNumber(brand(envelope.minimumSequenceNumber));
 	}
 
 	public getLocalBranch(): SharedTreeBranch<TEditor, TChange> {
-		return this.editManager.localBranch;
+		return this.editManager.getLocalBranch("main");
+	}
+
+	public getSharedBranchIds(): string[] {
+		return this.editManager
+			.getSharedBranchIds()
+			.filter((id): id is SessionSpaceCompressedId => id !== "main")
+			.map((id) => this.idCompressor.decompress(id));
+	}
+	public createSharedBranch(): string {
+		const branchId = this.idCompressor.generateCompressedId();
+		this.addBranch(branchId);
+		this.submitBranchCreation(branchId);
+		return this.idCompressor.decompress(branchId);
+	}
+
+	protected addBranch(branchId: BranchId): void {
+		this.editManager.addNewBranch(branchId);
+	}
+
+	public getSharedBranch(branchId: BranchId): SharedTreeBranch<TEditor, TChange> {
+		return this.editManager.getLocalBranch(branchId);
 	}
 
 	public didAttach(): void {
@@ -389,52 +487,150 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 
 	public reSubmitCore(content: JsonCompatibleReadOnly, localOpMetadata: unknown): void {
 		// Empty context object is passed in, as our decode function is schema-agnostic.
-		const {
-			commit: { revision },
-		} = this.messageCodec.decode(this.serializer.decode(content), {
+		const message = this.messageCodec.decode(this.serializer.decode(content), {
 			idCompressor: this.idCompressor,
 		});
-		// If a resubmit phase is not already in progress, then this must be the first commit of a new resubmit phase.
-		if (this.resubmitMachine.isInResubmitPhase === false) {
-			const localCommits = this.editManager.getLocalCommits();
-			const revisionIndex = localCommits.findIndex((c) => c.revision === revision);
-			assert(revisionIndex >= 0, 0xbdb /* revision must exist in local commits */);
-			const toResubmit = localCommits.slice(revisionIndex);
-			this.resubmitMachine.prepareForResubmit(toResubmit);
+
+		const type = message.type;
+		switch (type) {
+			case "commit": {
+				const {
+					commit: { revision },
+					branchId,
+				} = message;
+
+				const resubmitMachine = this.getResubmitMachine(branchId);
+				// If a resubmit phase is not already in progress, then this must be the first commit of a new resubmit phase.
+				if (resubmitMachine.isInResubmitPhase === false) {
+					const localCommits = this.editManager.getLocalCommits(branchId);
+					const revisionIndex = localCommits.findIndex((c) => c.revision === revision);
+					assert(revisionIndex >= 0, 0xbdb /* revision must exist in local commits */);
+					const toResubmit = localCommits.slice(revisionIndex);
+					resubmitMachine.prepareForResubmit(toResubmit);
+				}
+				assert(
+					isClonableSchemaPolicy(localOpMetadata),
+					0x95e /* Local metadata must contain schema and policy. */,
+				);
+				assert(
+					resubmitMachine.isInResubmitPhase !== false,
+					0x984 /* Invalid resubmit outside of resubmit phase */,
+				);
+				const enrichedCommit = resubmitMachine.peekNextCommit();
+				this.submitCommit(branchId, enrichedCommit, localOpMetadata, true);
+				break;
+			}
+			case "branch": {
+				this.submitBranchCreation(message.branchId);
+				break;
+			}
+			default:
+				unreachableCase(type);
 		}
-		assert(
-			isClonableSchemaPolicy(localOpMetadata),
-			0x95e /* Local metadata must contain schema and policy. */,
-		);
-		assert(
-			this.resubmitMachine.isInResubmitPhase !== false,
-			0x984 /* Invalid resubmit outside of resubmit phase */,
-		);
-		const enrichedCommit = this.resubmitMachine.peekNextCommit();
-		this.submitCommit(enrichedCommit, localOpMetadata, true);
 	}
+
 	public rollback(content: JsonCompatibleReadOnly, localOpMetadata: unknown): void {
 		// Empty context object is passed in, as our decode function is schema-agnostic.
-		const {
-			commit: { revision },
-		} = this.messageCodec.decode(this.serializer.decode(content), {
+		const message = this.messageCodec.decode(this.serializer.decode(content), {
 			idCompressor: this.idCompressor,
 		});
-		const [commit] = this.editManager.findLocalCommit(revision);
-		const { parent } = commit;
-		assert(parent !== undefined, 0xbdc /* must have parent */);
-		const [precedingCommit] = this.editManager.findLocalCommit(parent.revision);
-		this.editManager.localBranch.removeAfter(precedingCommit);
-		this.resubmitMachine.onCommitRollback(commit);
+
+		const type = message.type;
+		switch (type) {
+			case "commit": {
+				const {
+					commit: { revision },
+					branchId,
+				} = message;
+				const branch = this.editManager.getLocalBranch(branchId);
+				const head = branch.getHead();
+				assert(head.revision === revision, 0xc6b /* Can only rollback latest commit */);
+				const newHead = head.parent ?? fail(0xc6c /* must have parent */);
+				branch.removeAfter(newHead);
+				this.getResubmitMachine(branchId).onCommitRollback(head);
+				break;
+			}
+			case "branch": {
+				this.editManager.removeBranch(message.branchId);
+				break;
+			}
+			default:
+				unreachableCase(type);
+		}
 	}
 
 	public applyStashedOp(content: JsonCompatibleReadOnly): void {
 		// Empty context object is passed in, as our decode function is schema-agnostic.
-		const {
-			commit: { revision, change },
-		} = this.messageCodec.decode(content, { idCompressor: this.idCompressor });
-		this.editManager.localBranch.apply({ change, revision });
+		const message = this.messageCodec.decode(this.serializer.decode(content), {
+			idCompressor: this.idCompressor,
+		});
+
+		const type = message.type;
+		switch (type) {
+			case "commit": {
+				const {
+					commit: { revision, change },
+					branchId,
+				} = message;
+				this.editManager.getLocalBranch(branchId).apply({ change, revision });
+				break;
+			}
+			case "branch": {
+				this.editManager.addNewBranch(message.branchId);
+				break;
+			}
+			default:
+				unreachableCase(type);
+		}
+	}
+
+	protected registerSharedBranchForEditing(
+		branchId: BranchId,
+		enricher: ChangeEnricherReadonlyCheckout<TChange>,
+		resubmitMachine?: ResubmitMachine<TChange>,
+	): void {
+		const changeEnricher = enricher ?? new NoOpChangeEnricher();
+		const commitEnricher = new BranchCommitEnricher(this.changeFamily.rebaser, changeEnricher);
+		assert(!this.enrichers.has(branchId), 0xc6d /* Branch already registered */);
+		this.enrichers.set(branchId, {
+			enricher: commitEnricher,
+			resubmitMachine:
+				resubmitMachine ??
+				new DefaultResubmitMachine(
+					(change: TaggedChange<TChange>) =>
+						this.changeFamily.rebaser.invert(change, true, this.mintRevisionTag()),
+					changeEnricher,
+				),
+		});
+	}
+
+	private getResubmitMachine(branchId: BranchId): ResubmitMachine<TChange> {
+		return this.getEnricherState(branchId).resubmitMachine;
 	}
+
+	private tryGetResubmitMachine(branchId: BranchId): ResubmitMachine<TChange> | undefined {
+		return this.tryGetEnricherState(branchId)?.resubmitMachine;
+	}
+
+	public getCommitEnricher(branchId: BranchId): BranchCommitEnricher<TChange> {
+		return this.getEnricherState(branchId).enricher;
+	}
+
+	private getEnricherState(branchId: BranchId): EnricherState<TChange> {
+		return (
+			this.tryGetEnricherState(branchId) ??
+			fail(0xc6e /* Expected to have a resubmit machine for this branch */)
+		);
+	}
+
+	private tryGetEnricherState(branchId: BranchId): EnricherState<TChange> | undefined {
+		return this.enrichers.get(branchId);
+	}
+}
+
+interface EnricherState<TChange> {
+	readonly enricher: BranchCommitEnricher<TChange>;
+	readonly resubmitMachine: ResubmitMachine<TChange>;
 }
 
 function isClonableSchemaPolicy(

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

@@ -99,6 +99,27 @@ export interface ITreeAlpha extends ITree {
 	 * To get the schema using property keys, use {@link getSimpleSchema} on the view schema.
 	 */
 	exportSimpleSchema(): SimpleTreeSchema;
+
+	/**
+	 * Creates a fork of the current state of the main branch.
+	 * This new branch will be shared with and editable by all clients.
+	 */
+	createSharedBranch(): string;
+
+	/**
+	 * Returns a list of all shared branches that currently exist on this tree.
+	 * Any one of them can be checked out using {@link ITreeAlpha.viewSharedBranchWith}.
+	 */
+	getSharedBranchIds(): string[];
+
+	/**
+	 * Returns a view of the tree on the specified shared branch, using the provided schema.
+	 * See {@link ViewableTree.viewWith}.
+	 */
+	viewSharedBranchWith<TRoot extends ImplicitFieldSchema>(
+		branchId: string,
+		config: TreeViewConfiguration<TRoot>,
+	): TreeView<TRoot>;
 }
 
 /**
@@ -517,6 +538,8 @@ export interface TreeViewEvents {
 /**
  * Retrieve the {@link TreeViewAlpha | alpha API} for a {@link TreeView}.
  * @alpha
+ * @deprecated Use {@link asAlpha} instead.
+ * @privateRemarks Despite being deprecated, this function should be used within the tree package (outside of tests) rather than `asAlpha` in order to avoid circular import dependencies.
  */
 export function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(
 	view: TreeView<TSchema>,

package/src/simple-tree/core/unhydratedFlexTree.ts

@@ -50,6 +50,7 @@ import {
 	type HydratedFlexTreeNode,
 	cursorForMapTreeField,
 	type MinimalFieldMap,
+	currentObserver,
 } from "../../feature-libraries/index.js";
 import { brand, filterIterable, getOrCreate, mapIterable } from "../../util/index.js";
 
@@ -144,8 +145,10 @@ export class UnhydratedFlexTreeNode
 	 */
 	public readonly fields: MinimalFieldMap<UnhydratedFlexTreeField> = {
 		get: (key: FieldKey): UnhydratedFlexTreeField | undefined => this.tryGetField(key),
-		[Symbol.iterator]: (): IterableIterator<[FieldKey, UnhydratedFlexTreeField]> =>
-			filterIterable(this.fieldsAll, ([, field]) => field.length > 0),
+		[Symbol.iterator]: (): IterableIterator<[FieldKey, UnhydratedFlexTreeField]> => {
+			currentObserver?.observeNodeFields(this);
+			return filterIterable(this.fieldsAll, ([, field]) => field.length > 0);
+		},
 	};
 
 	public [Symbol.iterator](): IterableIterator<UnhydratedFlexTreeField> {
@@ -218,6 +221,7 @@ export class UnhydratedFlexTreeNode
 	 * @remarks If this node is unparented, this method will return the special {@link unparentedLocation} as the parent.
 	 */
 	public get parentField(): LocationInField {
+		currentObserver?.observeParentOf(this);
 		return this.location;
 	}
 
@@ -226,6 +230,8 @@ export class UnhydratedFlexTreeNode
 	}
 
 	public tryGetField(key: FieldKey): UnhydratedFlexTreeField | undefined {
+		currentObserver?.observeNodeField(this, key);
+
 		const field = this.fieldsAll.get(key);
 		// Only return the field if it is not empty, in order to fulfill the contract of `tryGetField`.
 		if (field !== undefined && field.length > 0) {
@@ -235,6 +241,9 @@ export class UnhydratedFlexTreeNode
 
 	public getBoxed(key: string): UnhydratedFlexTreeField {
 		const fieldKey: FieldKey = brand(key);
+
+		currentObserver?.observeNodeField(this, fieldKey);
+
 		return this.getOrCreateField(fieldKey);
 	}
 

package/src/treeFactory.ts

@@ -20,6 +20,7 @@ import {
 	SharedTreeKernel,
 	type ITreePrivate,
 	type SharedTreeOptions,
+	type SharedTreeOptionsBeta,
 	type SharedTreeOptionsInternal,
 	type SharedTreeKernelView,
 } from "./shared-tree/index.js";
@@ -91,26 +92,65 @@ export const SharedTree = configuredSharedTree({});
 /**
  * {@link SharedTree} but allowing a non-default configuration.
  * @remarks
- * This is useful for debugging and testing to opt into extra validation or see if opting out of some optimizations fixes an issue.
+ * This is useful for debugging and testing.
+ * For example it can be used to opt into extra validation or see if opting out of some optimizations fixes an issue.
+ *
+ * With great care, and knowledge of the support and stability of the options exposed here,
+ * this can also be used to opt into some features early or for performance tuning.
+ *
+ * @example
+ * ```typescript
+ * import {
+ * 	configuredSharedTreeBeta,
+ * 	ForestTypeReference,
+ * } from "fluid-framework/beta";
+ * const SharedTree = configuredSharedTree({
+ * 	forest: ForestTypeReference,
+ * });
+ * ```
+ * @privateRemarks
+ * The Legacy `ISharedObjectKind<ITree>` type is omitted here for simplicity.
+ * @beta
+ */
+export function configuredSharedTreeBeta(
+	options: SharedTreeOptionsBeta,
+): SharedObjectKind<ITree> {
+	return configuredSharedTree(options);
+}
+
+/**
+ * {@link configuredSharedTreeBeta} including the legacy `ISharedObjectKind` type.
+ * @privateRemarks
+ * This is given a different export name (with legacy appended) to avoid the need to do the special reexport with different types from the fluid-framework package.
+ * @legacy @beta
+ */
+export function configuredSharedTreeBetaLegacy(
+	options: SharedTreeOptionsBeta,
+): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {
+	return configuredSharedTree(options);
+}
+
+/**
+ * {@link configuredSharedTreeBetaLegacy} but including `@alpha` options.
+ *
  * @example
  * ```typescript
  * import {
- * 	ForestType,
  * 	TreeCompressionStrategy,
  * 	configuredSharedTree,
- * 	typeboxValidator,
+ * 	FormatValidatorBasic,
+ * 	ForestTypeReference,
  * } from "@fluidframework/tree/internal";
  * const SharedTree = configuredSharedTree({
  * 	forest: ForestTypeReference,
- * 	jsonValidator: typeboxValidator,
+ * 	jsonValidator: FormatValidatorBasic,
  * 	treeEncodeType: TreeCompressionStrategy.Uncompressed,
  * });
  * ```
  * @privateRemarks
- * This should be legacy, but has to be internal due to limitations of API tagging preventing it from being both alpha and alpha+legacy.
- * TODO:
- * Expose Ajv validator for better error message quality somehow.
- * Maybe as part of a test utils or dev-tool package?
+ * This should be legacy, but has to be internal due to no alpha+legacy being setup yet.
+ *
+ * This should be renamed to `configuredSharedTreeAlpha` to avoid colliding with the eventual public version which will have less options.
  * @internal
  */
 export function configuredSharedTree(