@fluidframework/tree 2.70.0-361248 → 2.70.0

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/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-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/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,
+			0xc87 /* 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>;
 }
 
 /**

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

@@ -60,7 +60,7 @@ export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
  * @privateRemarks
  * Since this is sealed, users are not supposed to create instances of it directly.
  * Making it extend ErasedType could enforce that.
- * @alpha
+ * @beta
  * @sealed
  */
 export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
@@ -77,7 +77,7 @@ export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
 /**
  * {@link AllowedTypesFull} but with the lazy schema references eagerly evaluated.
  * @sealed
- * @alpha
+ * @beta
  */
 export type AllowedTypesFullEvaluated = AllowedTypesFull<
 	readonly AnnotatedAllowedType<TreeNodeSchema>[]
@@ -95,7 +95,7 @@ export function isAnnotatedAllowedTypes(
 
 /**
  * Stores annotations for a set of allowed types.
- * @alpha
+ * @beta
  * @sealed
  */
 export interface AnnotatedAllowedTypes<T = readonly AnnotatedAllowedType[]>
@@ -139,7 +139,7 @@ export interface AnnotatedAllowedTypes<T = readonly AnnotatedAllowedType[]>
  * Stores annotations for a set of allowed types.
  * @remarks
  * Most expressive form of AllowedTypes which any of the implicit types can be normalized to.
- * @alpha
+ * @beta
  * @sealed
  */
 export type AllowedTypesFull<
@@ -148,8 +148,7 @@ export type AllowedTypesFull<
 
 /**
  * Creates an {@link AllowedTypesFull} type from a mixed array of annotated and unannotated allowed types.
- * @alpha
- * @sealed
+ * @system @sealed @beta
  */
 export type AllowedTypesFullFromMixed<
 	T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],
@@ -360,7 +359,7 @@ export class AnnotatedAllowedTypesInternal<
  * Annotations that apply to a set of allowed types.
  * @remarks
  * Additional optionals may be added to this as non-breaking changes, so implementations of it should be simple object literals with no unlisted members.
- * @alpha
+ * @beta
  * @input
  */
 export interface AllowedTypesMetadata {
@@ -385,7 +384,7 @@ export function isAnnotatedAllowedType(
  * Annotations that apply to an individual allowed type.
  * @remarks
  * Additional optionals may be added to this as non-breaking changes, so implementations of it should be simple object literals with no unlisted members.
- * @alpha
+ * @beta
  * @input
  */
 export interface AllowedTypeMetadata {
@@ -413,7 +412,7 @@ export let createSchemaUpgrade: () => SchemaUpgrade;
  * TODO:#38722 implement runtime schema upgrades.
  * Until then, the class purely behaves mostly as a placeholder.
  * TODO: Consider allowing users to store a name for the upgrade to use in error messages.
- * @sealed @alpha
+ * @sealed @beta
  */
 export class SchemaUpgrade {
 	protected _typeCheck!: MakeNominal;
@@ -461,7 +460,7 @@ export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
 
 /**
  * Removes annotations from a list of allowed types that may contain annotations.
- * @system @alpha
+ * @system @beta
  */
 export type UnannotateAllowedTypesList<
 	T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],
@@ -471,7 +470,7 @@ export type UnannotateAllowedTypesList<
 
 /**
  * Add annotations to a list of allowed types that may or may not contain annotations.
- * @system @alpha
+ * @system @beta
  */
 export type AnnotateAllowedTypesList<
 	T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],

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

@@ -16,7 +16,12 @@ export {
 	SimpleContextSlot,
 	withBufferedTreeEvents,
 } from "./treeNodeKernel.js";
-export { type WithType, typeNameSymbol, typeSchemaSymbol } from "./withType.js";
+export {
+	type WithType,
+	typeNameSymbol,
+	typeSchemaSymbol,
+	contentSchemaSymbol,
+} from "./withType.js";
 export {
 	type Unhydrated,
 	type InternalTreeNode,

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

@@ -5,6 +5,9 @@
 
 import type { TreeNode } from "./treeNode.js";
 import type { NodeKind, TreeNodeSchemaClass } from "./treeNodeSchema.js";
+// Used by doc links:
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
+import type { TreeAlpha } from "../../shared-tree/index.js";
 
 /**
  * The type of a {@link TreeNode}.
@@ -39,6 +42,27 @@ export const typeNameSymbol: unique symbol = Symbol("TreeNode Type");
  */
 export const typeSchemaSymbol: unique symbol = Symbol("TreeNode Schema");
 
+/**
+ * The intended type of insertable content that is to become a {@link TreeNode}.
+ * @remarks Use the type-safe {@link (TreeAlpha:interface).tagContentSchema} function to tag insertable content with this symbol.
+ *
+ * If a property with this symbol key is present on an object that is inserted into the tree,
+ * the tree will use the schema identifier specified by the value of this property when creating the node.
+ * This is particularly useful for specifying the intended schema of untyped content when it would otherwise be ambiguous.
+ * @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] }) {}
+ * // ...
+ * view.root.pet = { name: "Max" }; // Error: ambiguous schema - is it a Dog or a Cat?
+ * view.root.pet = { name: "Max", [contentSchemaSymbol]: "example.Dog" }; // No error - it's a Dog.
+ * ```
+ * @alpha
+ */
+export const contentSchemaSymbol: unique symbol = Symbol("SharedTree Schema");
+
 /**
  * Adds a type symbol to a type for stronger typing.
  *

package/src/simple-tree/index.ts

@@ -6,6 +6,7 @@
 export {
 	typeNameSymbol,
 	typeSchemaSymbol,
+	contentSchemaSymbol,
 	type WithType,
 	type TreeNodeSchema,
 	type AnnotatedAllowedType,
@@ -135,7 +136,9 @@ export {
 	type UnannotateAllowedTypesListUnsafe,
 	type AnnotateAllowedTypesListUnsafe,
 	type TreeViewAlpha,
+	type TreeViewBeta,
 	type TreeBranch,
+	type TreeBranchAlpha,
 	type TreeBranchEvents,
 	getPropertyKeyFromStoredKey,
 	getStoredKey,
@@ -180,6 +183,8 @@ export {
 	type SchemaStaticsAlpha,
 	KeyEncodingOptions,
 	type TreeParsingOptions,
+	incrementalSummaryHint,
+	getShouldIncrementallySummarizeAllowedTypes,
 	type SchemaFactory_base,
 } from "./api/index.js";
 export type {

package/src/simple-tree/unhydratedFlexTreeFromInsertable.ts

@@ -17,6 +17,7 @@ import {
 	isTreeNode,
 	type TreeNode,
 	type TreeNodeSchema,
+	contentSchemaSymbol,
 	type Unhydrated,
 	UnhydratedFlexTreeNode,
 } from "./core/index.js";
@@ -125,16 +126,28 @@ For class-based schema, this can be done by replacing an expression like "{foo:
 
 /**
  * Returns all types for which the data is schema-compatible.
+ * @remarks This will respect the {@link contentSchemaSymbol} property on data to disambiguate types - if present, only that type will be returned.
  */
 export function getPossibleTypes(
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
 	data: FactoryContent,
 ): TreeNodeSchema[] {
 	assert(data !== undefined, 0x889 /* undefined cannot be used as FactoryContent. */);
+	const type =
+		typeof data === "object" && data !== null
+			? (data as Partial<{ [contentSchemaSymbol]: string }>)[contentSchemaSymbol]
+			: undefined;
 
 	let best = CompatibilityLevel.None;
 	const possibleTypes: TreeNodeSchema[] = [];
 	for (const schema of allowedTypes) {
+		if (type !== undefined) {
+			if (schema.identifier === type) {
+				return [schema];
+			} else {
+				continue;
+			}
+		}
 		const handler = getTreeNodeSchemaPrivateData(schema).idempotentInitialize();
 		const level = handler.shallowCompatibilityTest(data);
 		if (level > best) {