@fluidframework/tree 2.42.0 → 2.43.0

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

@@ -275,7 +275,7 @@ export class SchemaCompatibilityTester {
 				}
 			}
 
-			return { kind: original.kind, types };
+			return { kind: original.kind, types, persistedMetadata: undefined };
 		}
 		return original;
 	}

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

@@ -32,7 +32,7 @@ import type { UnionToTuple } from "../../util/index.js";
  * This is commonly used in unions when the only information needed is which kind of node the value is.
  * Enums are a common example of this pattern.
  * @see {@link adaptEnum}
- * @alpha
+ * @beta
  */
 // Return type is intentionally derived.
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -107,7 +107,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * @privateRemarks
  * Maybe provide `SchemaFactory.nested` to ease creating nested scopes?
  * @see {@link enumFromStrings} for a similar function that works on arrays of strings instead of an enum.
- * @alpha
+ * @beta
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function adaptEnum<
@@ -186,7 +186,7 @@ export function adaptEnum<
  * class Parent extends schemaFactory.object("Parent", { mode: Mode.schema }) {}
  * ```
  * @see {@link adaptEnum} for a similar function that works on enums instead of arrays of strings.
- * @alpha
+ * @beta
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function enumFromStrings<

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

@@ -56,13 +56,14 @@ import {
 	createFieldSchema,
 	type DefaultProvider,
 	getDefaultProvider,
-	type NodeSchemaOptions,
 	markSchemaMostDerived,
 	type FieldSchemaAlpha,
 	type ImplicitAnnotatedAllowedTypes,
 	type UnannotateImplicitAllowedTypes,
 	type UnannotateSchemaRecord,
+	type NodeSchemaOptionsAlpha,
 	normalizeAllowedTypes,
+	type FieldPropsAlpha,
 } from "../schemaTypes.js";
 
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
@@ -101,7 +102,7 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
  * @alpha
  */
 export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown>
-	extends NodeSchemaOptions<TCustomMetadata> {
+	extends NodeSchemaOptionsAlpha<TCustomMetadata> {
 	/**
 	 * Allow nodes typed with this object node schema to contain optional fields that are not present in the schema declaration.
 	 * Such nodes can come into existence either via import APIs (see remarks) or by way of collaboration with another client
@@ -147,8 +148,12 @@ export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown>
 	allowUnknownOptionalFields?: boolean;
 }
 
+/**
+ * Default options for Object node schema creation.
+ * @remarks Omits parameters that are not relevant for common use cases.
+ */
 export const defaultSchemaFactoryObjectOptions: Required<
-	Omit<SchemaFactoryObjectOptions, "metadata">
+	Omit<SchemaFactoryObjectOptions, "metadata" | "persistedMetadata">
 > = {
 	allowUnknownOptionalFields: false,
 };
@@ -307,7 +312,7 @@ const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => []);
 
 function optional<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;
 
 function optional<
@@ -315,7 +320,7 @@ function optional<
 	const TCustomMetadata = unknown,
 >(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
 
 function optional<
@@ -323,7 +328,7 @@ function optional<
 	const TCustomMetadata = unknown,
 >(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {
 	return createFieldSchema(FieldKind.Optional, t, {
 		defaultProvider: defaultOptionalProvider,
@@ -333,7 +338,7 @@ function optional<
 
 function required<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;
 
 function required<
@@ -341,7 +346,7 @@ function required<
 	const TCustomMetadata = unknown,
 >(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
 
 function required<
@@ -349,7 +354,7 @@ function required<
 	const TCustomMetadata = unknown,
 >(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {
 	return createFieldSchema(FieldKind.Required, t, props);
 }
@@ -377,7 +382,7 @@ export const schemaStaticsBase = {
 		const TCustomMetadata = unknown,
 	>(
 		t: T,
-		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 	): FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata> => {
 		return createFieldSchemaUnsafe(FieldKind.Optional, t, {
 			defaultProvider: defaultOptionalProvider,
@@ -390,7 +395,7 @@ export const schemaStaticsBase = {
 		const TCustomMetadata = unknown,
 	>(
 		t: T,
-		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 	): FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata> => {
 		return createFieldSchemaUnsafe(FieldKind.Required, t, props);
 	},

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

@@ -23,7 +23,7 @@ import type {
 	ImplicitAnnotatedAllowedTypes,
 	ImplicitAnnotatedFieldSchema,
 	ImplicitFieldSchema,
-	NodeSchemaOptions,
+	NodeSchemaOptionsAlpha,
 } from "../schemaTypes.js";
 import type { RestrictiveStringRecord } from "../../util/index.js";
 import type { NodeKind, TreeNodeSchemaClass } from "../core/index.js";
@@ -88,6 +88,7 @@ export class SchemaFactoryAlpha<
 			options?.allowUnknownOptionalFields ??
 				defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
 			options?.metadata,
+			options?.persistedMetadata,
 		);
 	}
 
@@ -148,7 +149,7 @@ export class SchemaFactoryAlpha<
 	}
 
 	/**
-	 * {@inheritDoc SchemaStatics.optional}
+	 * {@inheritDoc SchemaStatics.leaves}
 	 */
 	public static override readonly leaves = schemaStatics.leaves;
 
@@ -167,11 +168,41 @@ export class SchemaFactoryAlpha<
 	 */
 	public static override readonly optionalRecursive = schemaStatics.optionalRecursive;
 
+	/**
+	 * {@inheritDoc SchemaStatics.requiredRecursive}
+	 */
+	public static override readonly requiredRecursive = schemaStatics.requiredRecursive;
+
 	/**
 	 * Like {@link SchemaFactory.identifier} but static and a factory function that can be provided {@link FieldProps}.
 	 */
 	public static readonly identifier = schemaStatics.identifier;
 
+	/**
+	 * {@inheritDoc SchemaStatics.leaves}
+	 */
+	public override readonly leaves = schemaStatics.leaves;
+
+	/**
+	 * {@inheritDoc SchemaStatics.optional}
+	 */
+	public override readonly optional = schemaStatics.optional;
+
+	/**
+	 * {@inheritDoc SchemaStatics.required}
+	 */
+	public override readonly required = schemaStatics.required;
+
+	/**
+	 * {@inheritDoc SchemaStatics.optionalRecursive}
+	 */
+	public override readonly optionalRecursive = schemaStatics.optionalRecursive;
+
+	/**
+	 * {@inheritDoc SchemaStatics.requiredRecursive}
+	 */
+	public override readonly requiredRecursive = schemaStatics.requiredRecursive;
+
 	/**
 	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
 	 *
@@ -193,9 +224,16 @@ export class SchemaFactoryAlpha<
 	>(
 		name: Name,
 		allowedTypes: T,
-		options?: NodeSchemaOptions<TCustomMetadata>,
+		options?: NodeSchemaOptionsAlpha<TCustomMetadata>,
 	): MapNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
-		return mapSchema(this.scoped2(name), allowedTypes, true, true, options?.metadata);
+		return mapSchema(
+			this.scoped2(name),
+			allowedTypes,
+			true,
+			true,
+			options?.metadata,
+			options?.persistedMetadata,
+		);
 	}
 
 	/**
@@ -206,7 +244,7 @@ export class SchemaFactoryAlpha<
 		Name extends TName,
 		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
-	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
+	>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {
 		return this.mapAlpha(
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,
@@ -237,9 +275,16 @@ export class SchemaFactoryAlpha<
 	>(
 		name: Name,
 		allowedTypes: T,
-		options?: NodeSchemaOptions<TCustomMetadata>,
+		options?: NodeSchemaOptionsAlpha<TCustomMetadata>,
 	): ArrayNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
-		return arraySchema(this.scoped2(name), allowedTypes, true, true, options?.metadata);
+		return arraySchema(
+			this.scoped2(name),
+			allowedTypes,
+			true,
+			true,
+			options?.metadata,
+			options?.persistedMetadata,
+		);
 	}
 
 	/**
@@ -250,7 +295,7 @@ export class SchemaFactoryAlpha<
 		const Name extends TName,
 		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
-	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
+	>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {
 		return this.arrayAlpha(
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,

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

@@ -12,7 +12,7 @@ import {
 } from "../../feature-libraries/index.js";
 import {
 	clientVersionToSchemaVersion,
-	type Format,
+	type FormatV1,
 	// eslint-disable-next-line import/no-internal-modules
 } from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
@@ -58,8 +58,8 @@ export function extractPersistedSchema(
 	oldestCompatibleClient: FluidClientVersion,
 ): JsonCompatible {
 	const stored = simpleToStoredSchema(schema);
-	const writeVersion = clientVersionToSchemaVersion(oldestCompatibleClient);
-	return encodeTreeSchema(stored, writeVersion);
+	const schemaWriteVersion = clientVersionToSchemaVersion(oldestCompatibleClient);
+	return encodeTreeSchema(stored, schemaWriteVersion);
 }
 
 /**
@@ -100,7 +100,7 @@ export function comparePersistedSchema(
 	// Any version can be passed down to makeSchemaCodec here.
 	// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.
 	const schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);
-	const stored = schemaCodec.decode(persisted as Format);
+	const stored = schemaCodec.decode(persisted as FormatV1);
 	const viewSchema = new SchemaCompatibilityTester(
 		defaultSchemaPolicy,
 		{},

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

@@ -26,7 +26,10 @@
  */
 export interface TreeChangeEvents {
 	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.
+	 * Emitted by a node if any changes affected the node.
+	 *
+	 * This event is emitted after all the changes in a batch have been applied to the whole tree.
+	 * This means that a handler for this event will be able to read the updated state of the tree.
 	 *
 	 * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).
 	 *
@@ -65,8 +68,10 @@ export interface TreeChangeEvents {
 	nodeChanged(unstable?: unknown): void;
 
 	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
-	 * subtree rooted at it.
+	 * Emitted by a node if something changed anywhere in the subtree rooted at it.
+	 *
+	 * This event is emitted after all the changes in a batch have been applied to the whole tree.
+	 * This means that a handler for this event will be able to read the updated state of the tree.
 	 *
 	 * @remarks
 	 * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.

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

@@ -39,7 +39,7 @@ import {
 } from "../core/index.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
 import { isObjectNodeSchema } from "../node-kinds/index.js";
-import { getTreeNodeForField } from "../getTreeNodeForField.js";
+import { tryGetTreeNodeForField } from "../getTreeNodeForField.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
@@ -83,6 +83,9 @@ export interface TreeNodeApi {
 	 * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).
 	 *
 	 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.
+	 *
+	 * @see {@link (TreeAlpha:interface).child}
+	 * @see {@link (TreeAlpha:interface).children}
 	 */
 	parent(node: TreeNode): TreeNode | undefined;
 
@@ -316,7 +319,7 @@ export function getIdentifierFromNode(
 			const key = identifierFieldKeys[0] ?? oob();
 			const identifierField = flexNode.tryGetField(key);
 			assert(identifierField !== undefined, 0xbb5 /* missing identifier field */);
-			const identifierValue = getTreeNodeForField(identifierField);
+			const identifierValue = tryGetTreeNodeForField(identifierField);
 			assert(typeof identifierValue === "string", 0xbb6 /* identifier not a string */);
 
 			const context = flexNode.context;

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

@@ -63,6 +63,7 @@ export function toSimpleTreeSchema(
 					allowedTypesIdentifiers: normalizedSchema.allowedTypesIdentifiers,
 					kind: normalizedSchema.kind,
 					metadata: normalizedSchema.metadata,
+					persistedMetadata: normalizedSchema.persistedMetadata,
 				} satisfies SimpleFieldSchema)
 			: normalizedSchema,
 		definitions,
@@ -94,6 +95,7 @@ function copySimpleLeafSchema(schema: SimpleLeafNodeSchema): SimpleLeafNodeSchem
 		kind: NodeKind.Leaf,
 		leafKind: schema.leafKind,
 		metadata: schema.metadata,
+		persistedMetadata: schema.persistedMetadata,
 	};
 }
 
@@ -104,6 +106,7 @@ function copySimpleMapOrArraySchema(
 		kind: schema.kind,
 		allowedTypesIdentifiers: schema.allowedTypesIdentifiers,
 		metadata: schema.metadata,
+		persistedMetadata: schema.persistedMetadata,
 	};
 }
 
@@ -115,6 +118,7 @@ function copySimpleObjectSchema(schema: SimpleObjectNodeSchema): SimpleObjectNod
 			kind: field.kind,
 			allowedTypesIdentifiers: field.allowedTypesIdentifiers,
 			metadata: field.metadata,
+			persistedMetadata: field.persistedMetadata,
 			storedKey: field.storedKey,
 		});
 	}
@@ -123,5 +127,6 @@ function copySimpleObjectSchema(schema: SimpleObjectNodeSchema): SimpleObjectNod
 		kind: NodeKind.Object,
 		fields,
 		metadata: schema.metadata,
+		persistedMetadata: schema.persistedMetadata,
 	};
 }

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

@@ -10,7 +10,7 @@ import type {
 } from "../../feature-libraries/index.js";
 import { brand } from "../../util/index.js";
 
-import type { TreeNodeSchema } from "./treeNodeSchema.js";
+import type { NormalizedAnnotatedAllowedTypes, TreeNodeSchema } from "./treeNodeSchema.js";
 import { walkAllowedTypes } from "./walkSchema.js";
 
 /**
@@ -52,7 +52,7 @@ export class Context {
 	 * Since this walks the schema, it must not be invoked during schema declaration or schema forward references could fail to be resolved.
 	 */
 	public constructor(
-		rootSchema: Iterable<TreeNodeSchema>,
+		rootSchema: NormalizedAnnotatedAllowedTypes,
 		public readonly flexContext: FlexTreeContext,
 	) {
 		const schema: Map<TreeNodeSchemaIdentifier, TreeNodeSchema> = new Map();
@@ -71,7 +71,7 @@ export class Context {
  */
 export class HydratedContext extends Context {
 	public constructor(
-		rootSchema: Iterable<TreeNodeSchema>,
+		rootSchema: NormalizedAnnotatedAllowedTypes,
 		public override readonly flexContext: FlexTreeHydratedContext,
 	) {
 		super(rootSchema, flexContext);

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

@@ -4,6 +4,8 @@
  */
 
 import type { TreeValue } from "../../core/index.js";
+import { isFlexTreeNode, type FlexTreeUnknownUnboxed } from "../../feature-libraries/index.js";
+import type { TreeLeafValue } from "../schemaTypes.js";
 
 import type { TreeNode } from "./treeNode.js";
 import {
@@ -34,3 +36,15 @@ export function getOrCreateNodeFromInnerNode(flexNode: InnerNode): TreeNode | Tr
 
 	return createTreeNodeFromInner(flexNode);
 }
+
+/**
+ * Returns the TreeNode or TreeValue for the provided {@link FlexTreeUnknownUnboxed}.
+ * This will allocate a new one if needed, and otherwise return one from cache.
+ * @remarks
+ * This supports both hydrated and unhydrated nodes.
+ */
+export function getOrCreateNodeFromInnerUnboxedNode(
+	flexTree: FlexTreeUnknownUnboxed,
+): TreeNode | TreeLeafValue {
+	return isFlexTreeNode(flexTree) ? getOrCreateNodeFromInnerNode(flexTree) : flexTree;
+}

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

@@ -31,10 +31,16 @@ export {
 	type TreeNodeSchemaNonClass,
 	type TreeNodeSchemaCore,
 	type TreeNodeSchemaBoth,
+	type AnnotatedAllowedType,
+	type NormalizedAnnotatedAllowedTypes,
+	isAnnotatedAllowedTypes,
 } from "./treeNodeSchema.js";
 export { walkAllowedTypes, type SchemaVisitor } from "./walkSchema.js";
 export { Context, HydratedContext, SimpleContextSlot } from "./context.js";
-export { getOrCreateNodeFromInnerNode } from "./getOrCreateNode.js";
+export {
+	getOrCreateNodeFromInnerNode,
+	getOrCreateNodeFromInnerUnboxedNode,
+} from "./getOrCreateNode.js";
 export {
 	UnhydratedFlexTreeNode,
 	UnhydratedSequenceField,

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

@@ -372,7 +372,7 @@ export function splitInnerNodeType(
 ): asserts innerNode is UnhydratedFlexTreeNode | HydratedFlexTreeNode {
 	assert(
 		innerNode instanceof UnhydratedFlexTreeNode || innerNode.isHydrated(),
-		"Invalid inner node type",
+		0xbc8 /* Invalid inner node type */,
 	);
 }
 
@@ -401,7 +401,7 @@ export function tryDisposeTreeNode(anchorNode: AnchorNode): void {
  */
 export function getSimpleNodeSchemaFromInnerNode(innerNode: InnerNode): TreeNodeSchema {
 	const context: Context = getSimpleContextFromInnerNode(innerNode);
-	return context.schema.get(innerNode.schema) ?? fail(0xb3f /* missing schema from context */);
+	return context.schema.get(innerNode.type) ?? fail(0xb3f /* missing schema from context */);
 }
 
 /**

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

@@ -3,7 +3,15 @@
  * Licensed under the MIT License.
  */
 
-import type { TreeLeafValue } from "../schemaTypes.js";
+import { assert } from "@fluidframework/core-utils/internal";
+import type { LazyItem } from "../flexList.js";
+import type {
+	AllowedTypeMetadata,
+	AllowedTypesMetadata,
+	AnnotatedAllowedTypes,
+	ImplicitAnnotatedAllowedTypes,
+	TreeLeafValue,
+} from "../schemaTypes.js";
 import type { SimpleNodeSchemaBase } from "../simpleSchema.js";
 
 import type { TreeNode } from "./treeNode.js";
@@ -62,6 +70,48 @@ export type TreeNodeSchema<
 			TCustomMetadata
 	  >;
 
+/**
+ * Stores annotations for an individual allowed type.
+ * @alpha
+ */
+export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
+	/**
+	 * Annotations for the allowed type.
+	 */
+	readonly metadata: AllowedTypeMetadata;
+	/**
+	 * The allowed type the annotations apply to in a particular schema.
+	 */
+	readonly type: T;
+}
+
+/**
+ * Stores annotations for a set of evaluated annotated allowed types.
+ * @alpha
+ */
+export interface NormalizedAnnotatedAllowedTypes {
+	/**
+	 * Annotations that apply to a set of allowed types.
+	 */
+	readonly metadata: AllowedTypesMetadata;
+	/**
+	 * All the evaluated allowed types that the annotations apply to. The types themselves are also individually annotated.
+	 */
+	readonly types: readonly AnnotatedAllowedType<TreeNodeSchema>[];
+}
+
+/**
+ * Checks if the input is an {@link AnnotatedAllowedTypes}.
+ */
+export function isAnnotatedAllowedTypes(
+	allowedTypes: ImplicitAnnotatedAllowedTypes,
+): allowedTypes is AnnotatedAllowedTypes {
+	return (
+		// Class based schema, and lazy schema references report type "function": filtering them out with typeof makes narrowing based on members mostly safe
+		typeof allowedTypes === "object" && "metadata" in allowedTypes && "types" in allowedTypes
+	);
+}
+
 /**
  * Schema which is not a class.
  * @remarks
@@ -231,8 +281,13 @@ export type TreeNodeSchemaBoth<
 
 /**
  * Data common to all tree node schema.
+ *
  * @remarks
  * Implementation detail of {@link TreeNodeSchema} which should be accessed instead of referring to this type directly.
+ *
+ * @privateRemarks
+ * All implementations must implement {@link TreeNodeSchemaCorePrivate} as well.
+ *
  * @sealed @public
  */
 export interface TreeNodeSchemaCore<
@@ -316,6 +371,63 @@ export interface TreeNodeSchemaCore<
 	createFromInsertable(data: TInsertable): Unhydrated<TreeNode | TreeLeafValue>;
 }
 
+/**
+ * {@link TreeNodeSchemaCore} extended with some non-exported APIs.
+ */
+export interface TreeNodeSchemaCorePrivate<
+	Name extends string = string,
+	Kind extends NodeKind = NodeKind,
+	TInsertable = never,
+	ImplicitlyConstructable extends boolean = boolean,
+	Info = unknown,
+	TCustomMetadata = unknown,
+> extends TreeNodeSchemaCore<
+		Name,
+		Kind,
+		ImplicitlyConstructable,
+		Info,
+		TInsertable,
+		TCustomMetadata
+	> {
+	/**
+	 * All possible annotated allowed types that a field under a node with this schema could have.
+	 * @remarks
+	 * In this case "field" includes anything that is a field in the internal (flex-tree) abstraction layer.
+	 * This includes the content field for arrays, and all the fields for map nodes.
+	 * If this node does not have fields (and thus is a leaf), the array will be empty.
+	 *
+	 * This set cannot be used before the schema in it have been defined:
+	 * more specifically, when using lazy schema references (for example to make foreword references to schema which have not yet been defined),
+	 * users must wait until after the schema are defined to access this array.
+	 *
+	 * @privateRemarks
+	 * If this is stabilized, it will live alongside the childTypes property on {@link TreeNodeSchemaCore}.
+	 * @system
+	 */
+	readonly childAnnotatedAllowedTypes: readonly NormalizedAnnotatedAllowedTypes[];
+}
+
+/**
+ * Downcasts a {@link TreeNodeSchemaCore} to {@link TreeNodeSchemaCorePrivate} if it is one.
+ *
+ * @remarks
+ * This function should only be used internally. The result should not be exposed publicly
+ * in any exported types or API return values.
+ */
+export function asTreeNodeSchemaCorePrivate(
+	schema: TreeNodeSchemaCore<string, NodeKind, boolean>,
+): TreeNodeSchemaCorePrivate {
+	assert(
+		"childAnnotatedAllowedTypes" in schema,
+		0xbc9 /* All implementations of TreeNodeSchemaCore must also implement TreeNodeSchemaCorePrivate */,
+	);
+	assert(
+		Array.isArray((schema as TreeNodeSchemaCorePrivate).childAnnotatedAllowedTypes),
+		0xbca /* All implementations of TreeNodeSchemaCore must also implement TreeNodeSchemaCorePrivate */,
+	);
+	return schema as TreeNodeSchemaCorePrivate;
+}
+
 /**
  * Kind of tree node.
  * @remarks