@fluidframework/tree 2.43.0-343119 → 2.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.43.0-343119",
+  "version": "2.43.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -89,17 +89,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "2.43.0-343119",
-    "@fluidframework/container-runtime": "2.43.0-343119",
-    "@fluidframework/core-interfaces": "2.43.0-343119",
-    "@fluidframework/core-utils": "2.43.0-343119",
-    "@fluidframework/datastore-definitions": "2.43.0-343119",
-    "@fluidframework/driver-definitions": "2.43.0-343119",
-    "@fluidframework/id-compressor": "2.43.0-343119",
-    "@fluidframework/runtime-definitions": "2.43.0-343119",
-    "@fluidframework/runtime-utils": "2.43.0-343119",
-    "@fluidframework/shared-object-base": "2.43.0-343119",
-    "@fluidframework/telemetry-utils": "2.43.0-343119",
+    "@fluid-internal/client-utils": "~2.43.0",
+    "@fluidframework/container-runtime": "~2.43.0",
+    "@fluidframework/core-interfaces": "~2.43.0",
+    "@fluidframework/core-utils": "~2.43.0",
+    "@fluidframework/datastore-definitions": "~2.43.0",
+    "@fluidframework/driver-definitions": "~2.43.0",
+    "@fluidframework/id-compressor": "~2.43.0",
+    "@fluidframework/runtime-definitions": "~2.43.0",
+    "@fluidframework/runtime-utils": "~2.43.0",
+    "@fluidframework/shared-object-base": "~2.43.0",
+    "@fluidframework/telemetry-utils": "~2.43.0",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@types/ungap__structured-clone": "^1.2.0",
@@ -109,19 +109,19 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "2.43.0-343119",
-    "@fluid-private/stochastic-test-utils": "2.43.0-343119",
-    "@fluid-private/test-dds-utils": "2.43.0-343119",
-    "@fluid-private/test-drivers": "2.43.0-343119",
+    "@fluid-internal/mocha-test-setup": "~2.43.0",
+    "@fluid-private/stochastic-test-utils": "~2.43.0",
+    "@fluid-private/test-dds-utils": "~2.43.0",
+    "@fluid-private/test-drivers": "~2.43.0",
     "@fluid-tools/benchmark": "^0.51.0",
-    "@fluid-tools/build-cli": "^0.55.0",
+    "@fluid-tools/build-cli": "^0.56.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.55.0",
-    "@fluidframework/container-definitions": "2.43.0-343119",
-    "@fluidframework/container-loader": "2.43.0-343119",
+    "@fluidframework/build-tools": "^0.56.0",
+    "@fluidframework/container-definitions": "~2.43.0",
+    "@fluidframework/container-loader": "~2.43.0",
     "@fluidframework/eslint-config-fluid": "^5.7.4",
-    "@fluidframework/test-runtime-utils": "2.43.0-343119",
-    "@fluidframework/test-utils": "2.43.0-343119",
+    "@fluidframework/test-runtime-utils": "~2.43.0",
+    "@fluidframework/test-utils": "~2.43.0",
     "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.42.0",
     "@microsoft/api-extractor": "7.52.8",
     "@types/diff": "^3.5.1",

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -169,7 +169,7 @@ export interface FlexTreeNode extends FlexTreeEntity, MapTreeNodeViewGeneric<Fle
 	 * @remarks
 	 * All fields implicitly exist, so `getBoxed` can be called with any key and will always return a field.
 	 * Even if the field is empty, it will still be returned, and can be edited to insert content if allowed by the field kind.
-	 * See {@link FlexTreeNode.tryGetField} for a variant that does not allocate afield in the empty case.
+	 * See {@link FlexTreeNode.tryGetField} for a variant that does not allocate a field in the empty case.
 	 */
 	getBoxed(key: FieldKey): FlexTreeField;
 

package/src/index.ts

@@ -158,6 +158,7 @@ export {
 	type ImplicitAnnotatedFieldSchema,
 	type AnnotatedAllowedType,
 	type AnnotatedAllowedTypes,
+	type NormalizedAnnotatedAllowedTypes,
 	type AllowedTypeMetadata,
 	type AllowedTypesMetadata,
 	type InsertableObjectFromAnnotatedSchemaRecord,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.43.0-343119";
+export const pkgVersion = "2.43.0";

package/src/shared-tree/schematizingTreeView.ts

@@ -22,12 +22,11 @@ import {
 	TreeStatus,
 } from "../feature-libraries/index.js";
 import {
-	type FieldSchema,
 	type ImplicitFieldSchema,
 	type SchemaCompatibilityStatus,
 	type TreeView,
 	type TreeViewEvents,
-	getTreeNodeForField,
+	tryGetTreeNodeForField,
 	setField,
 	normalizeFieldSchema,
 	SchemaCompatibilityTester,
@@ -53,6 +52,7 @@ import {
 	areImplicitFieldSchemaEqual,
 	createUnknownOptionalFieldPolicy,
 	prepareForInsertionContextless,
+	type FieldSchema,
 } from "../simple-tree/index.js";
 import {
 	type Breakable,
@@ -353,7 +353,10 @@ export class SchematizingSimpleTreeView<
 			);
 			this.checkout.forest.anchors.slots.set(
 				SimpleContextSlot,
-				new HydratedContext(this.rootFieldSchema.allowedTypeSet, view.context),
+				new HydratedContext(
+					normalizeFieldSchema(this.rootFieldSchema).annotatedAllowedTypesNormalized,
+					view.context,
+				),
 			);
 
 			const unregister = this.checkout.storedSchema.events.on("afterSchemaChange", () => {
@@ -428,7 +431,7 @@ export class SchematizingSimpleTreeView<
 			);
 		}
 		const view = this.getView();
-		return getTreeNodeForField(view.flexTree) as ReadableField<TRootSchema>;
+		return tryGetTreeNodeForField(view.flexTree) as ReadableField<TRootSchema>;
 	}
 
 	public set root(newRoot: InsertableField<TRootSchema>) {
@@ -525,7 +528,7 @@ export function addConstraintsToTransaction(
 						`Attempted to add a "nodeInDocument" constraint${revertText}, but the node is not currently in the document. Node status: ${nodeStatus}`,
 					);
 				}
-				assert(node.isHydrated(), "In document node must be hydrated.");
+				assert(node.isHydrated(), 0xbc2 /* In document node must be hydrated. */);
 				if (constraintsOnRevert) {
 					checkout.editor.addNodeExistsConstraintOnRevert(node.anchorNode);
 				} else {

package/src/shared-tree/treeAlpha.ts

@@ -3,13 +3,19 @@
  * Licensed under the MIT License.
  */
 
-import { assert, fail } from "@fluidframework/core-utils/internal";
+import {
+	assert,
+	debugAssert,
+	fail,
+	unreachableCase,
+} from "@fluidframework/core-utils/internal";
 import { createIdCompressor } from "@fluidframework/id-compressor/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
+	asIndex,
 	getKernel,
 	type TreeNode,
 	type Unhydrated,
@@ -40,15 +46,20 @@ import {
 	getIdentifierFromNode,
 	unhydratedFlexTreeFromInsertable,
 	getOrCreateNodeFromInnerNode,
+	getOrCreateNodeFromInnerUnboxedNode,
+	getOrCreateInnerNode,
+	NodeKind,
+	tryGetTreeNodeForField,
+	isObjectNodeSchema,
 } from "../simple-tree/index.js";
-import { extractFromOpaque, type JsonCompatible } from "../util/index.js";
+import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import {
 	FluidClientVersion,
 	noopValidator,
 	type ICodecOptions,
 	type CodecWriteOptions,
 } from "../codec/index.js";
-import type { ITreeCursorSynchronous } from "../core/index.js";
+import { EmptyKey, type ITreeCursorSynchronous } from "../core/index.js";
 import {
 	cursorForMapTreeField,
 	defaultSchemaPolicy,
@@ -60,6 +71,7 @@ import {
 	type FieldBatchEncodingContext,
 	fluidVersionToFieldBatchCodecWriteVersion,
 	type LocalNodeIdentifier,
+	type FlexTreeSequenceField,
 } from "../feature-libraries/index.js";
 import { independentInitializedView, type ViewContent } from "./independentView.js";
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
@@ -343,6 +355,48 @@ export interface TreeAlpha {
 	 * Otherwise, this returns the key of the field that it is under (a `string`).
 	 */
 	key2(node: TreeNode): string | number | undefined;
+
+	/**
+	 * Gets the child of the given node with the given property key if a child exists under that key.
+	 *
+	 * @remarks {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields | Unknown optional fields} of Object nodes will not be returned by this method.
+	 *
+	 * @param node - The parent node whose child is being requested.
+	 * @param key - The property key under the node under which the child is being requested.
+	 * For Object nodes, this is the developer-facing "property key", not the "{@link SimpleObjectFieldSchema.storedKey | stored keys}".
+	 *
+	 * @returns The child node or leaf value under the given key, or `undefined` if no such child exists.
+	 *
+	 * @see {@link (TreeAlpha:interface).key2}
+	 * @see {@link (TreeNodeApi:interface).parent}
+	 */
+	child(node: TreeNode, key: string | number): TreeNode | TreeLeafValue | undefined;
+
+	/**
+	 * Gets the children of the provided node, paired with their property keys under the node.
+	 *
+	 * @remarks
+	 * No guarantees are made regarding the order of the children in the returned array.
+	 *
+	 * Optional properties of Object nodes with no value are not included in the result.
+	 *
+	 * {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields | Unknown optional fields} of Object nodes are not included in the result.
+	 *
+	 * @param node - The node whose children are being requested.
+	 *
+	 * @returns
+	 * An array of pairs of the form `[propertyKey, child]`.
+	 *
+	 * For Array nodes, the `propertyKey` is the index of the child in the array.
+	 *
+	 * For Object nodes, the returned `propertyKey`s are the developer-facing "property keys", not the "{@link SimpleObjectFieldSchema.storedKey | stored keys}".
+	 *
+	 * @see {@link (TreeAlpha:interface).key2}
+	 * @see {@link (TreeNodeApi:interface).parent}
+	 */
+	children(
+		node: TreeNode,
+	): Iterable<[propertyKey: string | number, child: TreeNode | TreeLeafValue]>;
 }
 
 /**
@@ -492,6 +546,137 @@ export const TreeAlpha: TreeAlpha = {
 		const parentSchema = treeNodeApi.schema(parent);
 		return getPropertyKeyFromStoredKey(parentSchema, storedKey);
 	},
+
+	child: (
+		node: TreeNode,
+		propertyKey: string | number,
+	): TreeNode | TreeLeafValue | undefined => {
+		const flexNode = getOrCreateInnerNode(node);
+		debugAssert(
+			() => !flexNode.context.isDisposed() || "The provided tree node has been disposed.",
+		);
+
+		const schema = treeNodeApi.schema(node);
+
+		switch (schema.kind) {
+			case NodeKind.Array: {
+				const sequence = flexNode.tryGetField(EmptyKey) as FlexTreeSequenceField | undefined;
+
+				// Empty sequence - cannot have children.
+				if (sequence === undefined) {
+					return undefined;
+				}
+
+				const index =
+					typeof propertyKey === "number"
+						? propertyKey
+						: asIndex(propertyKey, Number.POSITIVE_INFINITY);
+
+				// If the key is not a valid index, then there is no corresponding child.
+				if (index === undefined) {
+					return undefined;
+				}
+
+				const childFlexTree = sequence.at(index);
+
+				// No child at the given index.
+				if (childFlexTree === undefined) {
+					return undefined;
+				}
+
+				return getOrCreateNodeFromInnerUnboxedNode(childFlexTree);
+			}
+			case NodeKind.Map:
+				if (typeof propertyKey !== "string") {
+					// Map nodes only support string keys.
+					return undefined;
+				}
+			// Fall through
+			case NodeKind.Object: {
+				let storedKey: string | number = propertyKey;
+				if (isObjectNodeSchema(schema)) {
+					const fieldSchema = schema.fields.get(String(propertyKey));
+					if (fieldSchema === undefined) {
+						return undefined;
+					}
+
+					storedKey = fieldSchema.storedKey;
+				}
+
+				const field = flexNode.tryGetField(brand(String(storedKey)));
+				if (field !== undefined) {
+					return tryGetTreeNodeForField(field);
+				}
+
+				return undefined;
+			}
+			case NodeKind.Leaf: {
+				fail(0xbc3 /* Leaf schema associated with non-leaf tree node. */);
+			}
+			default: {
+				unreachableCase(schema.kind);
+			}
+		}
+	},
+
+	children(node: TreeNode): [propertyKey: string | number, child: TreeNode | TreeLeafValue][] {
+		const flexNode = getOrCreateInnerNode(node);
+		debugAssert(
+			() => !flexNode.context.isDisposed() || "The provided tree node has been disposed.",
+		);
+
+		const schema = treeNodeApi.schema(node);
+
+		const result: [string | number, TreeNode | TreeLeafValue][] = [];
+		switch (schema.kind) {
+			case NodeKind.Array: {
+				const sequence = flexNode.tryGetField(EmptyKey) as FlexTreeSequenceField | undefined;
+				if (sequence === undefined) {
+					break;
+				}
+
+				for (let index = 0; index < sequence.length; index++) {
+					const childFlexTree = sequence.at(index);
+					assert(childFlexTree !== undefined, 0xbc4 /* Sequence child was undefined. */);
+					const childTree = getOrCreateNodeFromInnerUnboxedNode(childFlexTree);
+					result.push([index, childTree]);
+				}
+				break;
+			}
+			case NodeKind.Map: {
+				for (const [key, flexField] of flexNode.fields) {
+					const childTreeNode = tryGetTreeNodeForField(flexField);
+					if (childTreeNode !== undefined) {
+						result.push([key, childTreeNode]);
+					}
+				}
+				break;
+			}
+			case NodeKind.Object: {
+				assert(isObjectNodeSchema(schema), 0xbc5 /* Expected object schema. */);
+				for (const [propertyKey, fieldSchema] of schema.fields) {
+					const storedKey = fieldSchema.storedKey;
+					const flexField = flexNode.tryGetField(brand(String(storedKey)));
+					if (flexField !== undefined) {
+						const childTreeNode = tryGetTreeNodeForField(flexField);
+						assert(
+							childTreeNode !== undefined,
+							0xbc6 /* Expected child tree node for field. */,
+						);
+						result.push([propertyKey, childTreeNode]);
+					}
+				}
+				break;
+			}
+			case NodeKind.Leaf: {
+				fail(0xbc7 /* Leaf schema associated with non-leaf tree node. */);
+			}
+			default: {
+				unreachableCase(schema.kind);
+			}
+		}
+		return result;
+	},
 };
 
 function exportConcise(

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

@@ -3,13 +3,15 @@
  * Licensed under the MIT License.
  */
 
-import { assert, fail } from "@fluidframework/core-utils/internal";
+import { assert, debugAssert, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	type FieldSchemaAlpha,
 	type ImplicitFieldSchema,
+	evaluateLazySchema,
 	FieldKind,
+	isAnnotatedAllowedType,
 	markSchemaMostDerived,
 	normalizeFieldSchema,
 } from "../schemaTypes.js";
@@ -159,6 +161,11 @@ export class TreeViewConfiguration<
 	 */
 	public readonly preventAmbiguity: boolean;
 
+	/**
+	 * {@link TreeSchema.definitions} but with public types.
+	 */
+	protected readonly definitionsInternal: ReadonlyMap<string, TreeNodeSchema>;
+
 	/**
 	 * Construct a new {@link TreeViewConfiguration}.
 	 *
@@ -181,27 +188,38 @@ export class TreeViewConfiguration<
 		// Ambiguity errors are lower priority to report than invalid schema errors, so collect these in an array and report them all at once.
 		const ambiguityErrors: string[] = [];
 
+		// Eagerly perform this conversion to surface errors sooner.
+		// Includes detection of duplicate schema identifiers.
+		toStoredSchema(config.schema);
+
+		const definitions = new Map<string, SimpleNodeSchema & TreeNodeSchema>();
+
 		walkFieldSchema(config.schema, {
-			// Ensure all reachable schema are marked as most derived.
-			// This ensures if multiple schema extending the same schema factory generated class are present (or have been constructed, or get constructed in the future),
-			// an error is reported.
-
-			node: (schema) => markSchemaMostDerived(schema, true),
-			allowedTypes(types): void {
-				if (config.preventAmbiguity) {
-					checkUnion(types, ambiguityErrors);
-				}
+			node: (schema) => {
+				// Ensure all reachable schema are marked as most derived.
+				// This ensures if multiple schema extending the same schema factory generated class are present (or have had instances of them constructed, or get instances of them constructed in the future),
+				// an error is reported.
+				markSchemaMostDerived(schema, true);
+
+				debugAssert(() => !definitions.has(schema.identifier));
+				definitions.set(schema.identifier, schema as SimpleNodeSchema & TreeNodeSchema);
+			},
+			allowedTypes({ types }): void {
+				checkUnion(
+					types.map((t) => evaluateLazySchema(isAnnotatedAllowedType(t) ? t.type : t)),
+					config.preventAmbiguity,
+					ambiguityErrors,
+				);
 			},
 		});
 
+		this.definitionsInternal = definitions;
+
 		if (ambiguityErrors.length !== 0) {
 			// Duplicate errors are common since when two types conflict, both orders error:
 			const deduplicated = new Set(ambiguityErrors);
 			throw new UsageError(`Ambiguous schema found:\n${[...deduplicated].join("\n")}`);
 		}
-
-		// Eagerly perform this conversion to surface errors sooner.
-		toStoredSchema(config.schema);
 	}
 }
 
@@ -219,20 +237,17 @@ export class TreeViewConfigurationAlpha<
 	 * {@inheritDoc TreeSchema.root}
 	 */
 	public readonly root: FieldSchemaAlpha;
+
 	/**
 	 * {@inheritDoc TreeSchema.definitions}
 	 */
-	public readonly definitions: ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
+	public get definitions(): ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema> {
+		return this.definitionsInternal as ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
+	}
 
 	public constructor(props: ITreeViewConfiguration<TSchema>) {
 		super(props);
 		this.root = normalizeFieldSchema(props.schema);
-		const definitions = new Map<string, SimpleNodeSchema & TreeNodeSchema>();
-		walkFieldSchema(props.schema, {
-			node: (schema) =>
-				definitions.set(schema.identifier, schema as SimpleNodeSchema & TreeNodeSchema),
-		});
-		this.definitions = definitions;
 	}
 }
 
@@ -262,9 +277,21 @@ function formatTypes(allowed: Iterable<TreeNodeSchema>): string {
 }
 
 /**
- * Detect cases documented in {@link ITreeConfigurationOptions.preventAmbiguity}.
+ * Check if union contents are valid (shallowly).
+ *
+ * @param union - The union of {@link TreeNodeSchema} to check.
+ * @param preventAmbiguity - If true, detect cases documented in {@link ITreeConfigurationOptions.preventAmbiguity}, reporting them to `ambiguityErrors`.
+ * @param ambiguityErrors - An array into which this function inserts any ambiguity errors, see {@link ITreeConfigurationOptions.preventAmbiguity}.
+ *
+ * @remarks
+ * Includes checks for non-ambiguity errors as well: such as duplicate schemas in the union.
+ * Any non-ambiguity errors are thrown as exceptions: `UsageError`s if causable by incorrect API use, and asserts if violating internal invariants.
  */
-export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): void {
+export function checkUnion(
+	union: Iterable<TreeNodeSchema>,
+	preventAmbiguity: boolean,
+	ambiguityErrors: string[],
+): void {
 	const checked: Set<TreeNodeSchema> = new Set();
 	const maps: TreeNodeSchema[] = [];
 	const arrays: TreeNodeSchema[] = [];
@@ -294,26 +321,31 @@ export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): v
 		}
 	}
 
+	if (!preventAmbiguity) {
+		// All remaining checks are for the preventAmbiguity case, so skip them if not enabled.
+		return;
+	}
+
 	if (arrays.length > 1) {
-		errors.push(
+		ambiguityErrors.push(
 			`More than one kind of array allowed within union (${formatTypes(arrays)}). This would require type disambiguation which is not supported by arrays during import or export.`,
 		);
 	}
 
 	if (maps.length > 1) {
-		errors.push(
+		ambiguityErrors.push(
 			`More than one kind of map allowed within union (${formatTypes(maps)}). This would require type disambiguation which is not supported by maps during import or export.`,
 		);
 	}
 
 	if (maps.length > 0 && arrays.length > 0) {
-		errors.push(
+		ambiguityErrors.push(
 			`Both a map and an array allowed within union (${formatTypes([...arrays, ...maps])}). Both can be implicitly constructed from iterables like arrays, which are ambiguous when the array is empty.`,
 		);
 	}
 
 	if (objects.length > 0 && maps.length > 0) {
-		errors.push(
+		ambiguityErrors.push(
 			`Both a object and a map allowed within union (${formatTypes([...objects, ...maps])}). Both can be constructed from objects and can be ambiguous.`,
 		);
 	}
@@ -345,7 +377,7 @@ export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): v
 			// Consider separating unambiguous implicit construction format from constructor arguments at type level, allowing constructor to superset the implicit construction options (ex: optional constant fields).
 			// The policy here however must remain at least as conservative as shallowCompatibilityTest in src/simple-tree/unhydratedFlexTreeFromInsertable.ts.
 
-			errors.push(
+			ambiguityErrors.push(
 				`The required fields of ${JSON.stringify(schema.identifier)} are insufficient to differentiate it from the following types: ${formatTypes(possiblyAmbiguous)}. For objects to be considered unambiguous, each must have required fields that do not all occur on any other object in the union.`,
 			);
 		}

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

@@ -45,12 +45,12 @@ export {
 	singletonSchema,
 } from "./schemaCreationUtilities.js";
 export {
+	getIdentifierFromNode,
+	getPropertyKeyFromStoredKey,
+	getStoredKey,
 	treeNodeApi,
 	type TreeNodeApi,
 	tryGetSchema,
-	getStoredKey,
-	getPropertyKeyFromStoredKey,
-	getIdentifierFromNode,
 } from "./treeNodeApi.js";
 export { createFromCursor } from "./create.js";
 export {

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/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,