@fluidframework/tree 2.41.0 → 2.43.0-343119

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

@@ -6,14 +6,15 @@
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { TreeValue } from "../../core/index.js";
-import type { NodeIdentifierManager } from "../../feature-libraries/index.js";
 // This import is required for intellisense in @link doc comments on mouseover in VSCode.
 // eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
 import type { TreeAlpha } from "../../shared-tree/index.js";
 import {
 	type RestrictiveStringRecord,
+	compareSets,
 	getOrCreate,
 	isReadonlyArray,
 } from "../../util/index.js";
@@ -24,6 +25,7 @@ import type {
 	TreeNodeSchemaClass,
 	TreeNodeSchemaNonClass,
 	TreeNodeSchemaBoth,
+	UnhydratedFlexTreeNode,
 } from "../core/index.js";
 import { isLazy } from "../flexList.js";
 import {
@@ -54,16 +56,22 @@ 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";
 import type { System_Unsafe, FieldSchemaAlphaUnsafe } from "./typesUnsafe.js";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
+import { createIdCompressor } from "@fluidframework/id-compressor/internal";
+import type { FlexTreeHydratedContextMinimal } from "../../feature-libraries/index.js";
+import { unhydratedFlexTreeFromInsertable } from "../unhydratedFlexTreeFromInsertable.js";
 
 /**
  * Gets the leaf domain schema compatible with a given {@link TreeValue}.
@@ -94,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
@@ -140,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,
 };
@@ -293,16 +305,14 @@ export interface SchemaStatics {
 	) => System_Unsafe.FieldSchemaUnsafe<FieldKind.Required, T, TCustomMetadata>;
 }
 
-const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => {
-	return undefined;
-});
+const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => []);
 
 // The following overloads for optional and required are used to get around the fact that
 // the compiler can't infer that UnannotateImplicitAllowedTypes<T> is equal to T when T is known to extend ImplicitAllowedTypes
 
 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<
@@ -310,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<
@@ -318,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,
@@ -328,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<
@@ -336,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<
@@ -344,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);
 }
@@ -372,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,
@@ -385,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);
 	},
@@ -766,9 +776,9 @@ export class SchemaFactory<
 		if (allowedTypes === undefined) {
 			const types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];
 			const fullName = structuralName("Map", types);
-			return getOrCreate(
-				this.structuralTypes,
+			return this.getStructuralType(
 				fullName,
+				types,
 				() =>
 					this.namedMap(
 						fullName as TName,
@@ -954,7 +964,7 @@ export class SchemaFactory<
 		if (allowedTypes === undefined) {
 			const types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];
 			const fullName = structuralName("Array", types);
-			return getOrCreate(this.structuralTypes, fullName, () =>
+			return this.getStructuralType(fullName, types, () =>
 				this.namedArray(fullName, nameOrAllowedTypes as T, false, true),
 			) as TreeNodeSchemaClass<
 				ScopedSchemaName<TScope, string>,
@@ -978,6 +988,35 @@ export class SchemaFactory<
 		return out;
 	}
 
+	/**
+	 * Retrieves or creates a structural {@link TreeNodeSchema} with the specified name and types.
+	 *
+	 * @param fullName - The name for the structural schema.
+	 * @param types - The input schema(s) used to define the structural schema.
+	 * @param builder - A function that builds the schema if it does not already exist.
+	 * @returns The structural {@link TreeNodeSchema} associated with the given name and types.
+	 * @throws `UsageError` if a schema structurally named schema with the same name is cached in `structuralTypes` but had different input types.
+	 */
+	private getStructuralType(
+		fullName: string,
+		types: TreeNodeSchema | readonly TreeNodeSchema[],
+		builder: () => TreeNodeSchema,
+	): TreeNodeSchema {
+		const structural = getOrCreate(this.structuralTypes, fullName, builder);
+		const inputTypes = new Set(normalizeAllowedTypes(types));
+		const outputTypes = new Set(
+			normalizeAllowedTypes(structural.info as TreeNodeSchema | readonly TreeNodeSchema[]),
+		);
+		// If our cached value had a different set of types then were requested, the user must have caused a collision.
+		const same = compareSets({ a: inputTypes, b: outputTypes });
+		if (!same) {
+			throw new UsageError(
+				`Structurally named schema collision: two schema named "${fullName}" were defined with different input schema.`,
+			);
+		}
+		return structural;
+	}
+
 	/**
 	 * Define a {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.
 	 *
@@ -1080,8 +1119,6 @@ export class SchemaFactory<
 	 *
 	 * - A compressed form of the identifier can be accessed at runtime via the {@link TreeNodeApi.shortId|Tree.shortId()} API.
 	 *
-	 * - It will not be present in the object's iterable properties until explicitly read or until having been inserted into a tree.
-	 *
 	 * However, a user may alternatively supply their own string as the identifier if desired (for example, if importing identifiers from another system).
 	 * In that case, if the user requires it to be unique, it is up to them to ensure uniqueness.
 	 * User-supplied identifiers may be read immediately, even before insertion into the tree.
@@ -1090,10 +1127,19 @@ export class SchemaFactory<
 	 */
 	public get identifier(): FieldSchema<FieldKind.Identifier, typeof this.string> {
 		const defaultIdentifierProvider: DefaultProvider = getDefaultProvider(
-			(nodeKeyManager: NodeIdentifierManager) => {
-				return nodeKeyManager.stabilizeNodeIdentifier(
-					nodeKeyManager.generateLocalNodeIdentifier(),
-				);
+			(
+				context: FlexTreeHydratedContextMinimal | "UseGlobalContext",
+			): UnhydratedFlexTreeNode[] => {
+				const id =
+					context === "UseGlobalContext"
+						? globalIdentifierAllocator.decompress(
+								globalIdentifierAllocator.generateCompressedId(),
+							)
+						: context.nodeKeyManager.stabilizeNodeIdentifier(
+								context.nodeKeyManager.generateLocalNodeIdentifier(),
+							);
+
+				return [unhydratedFlexTreeFromInsertable(id, this.string)];
 			},
 		);
 		return createFieldSchema(FieldKind.Identifier, this.string, {
@@ -1266,3 +1312,11 @@ export function structuralName<const T extends string>(
 	}
 	return `${collectionName}<${inner}>`;
 }
+
+/**
+ * Used to allocate default identifiers for unhydrated nodes when no context is available.
+ * @remarks
+ * The identifiers allocated by this will never be compressed to Short Ids.
+ * Using this is only better than creating fully random V4 UUIDs because it reduces the entropy making it possible for things like text compression to work slightly better.
+ */
+const globalIdentifierAllocator: IIdCompressor = createIdCompressor();

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob, fail } from "@fluidframework/core-utils/internal";
+import { assert, oob, fail, unreachableCase } from "@fluidframework/core-utils/internal";
 
 import { EmptyKey, rootFieldKey } from "../../core/index.js";
 import { type TreeStatus, isTreeValue, FieldKinds } from "../../feature-libraries/index.js";
@@ -34,17 +34,23 @@ import {
 	type TreeNode,
 	tryGetTreeNodeSchema,
 	getOrCreateNodeFromInnerNode,
-	UnhydratedFlexTreeNode,
 	typeSchemaSymbol,
 	getOrCreateInnerNode,
 } from "../core/index.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
-import { lazilyAllocateIdentifier, isObjectNodeSchema } from "../node-kinds/index.js";
+import { isObjectNodeSchema } from "../node-kinds/index.js";
+import { getTreeNodeForField } from "../getTreeNodeForField.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
- * * @remarks
- * This type should only be used via the public `Tree` export.
+ *
+ * @remarks
+ * With the exception of {@link TreeNodeApi.status}, these functions should not be called with nodes that have
+ * been {@link TreeStatus.Deleted | deleted}.
+ * To verify whether or not a node already has been deleted, use the {@link TreeNodeApi.status} function.
+ *
+ * This type should only be used via the public {@link (Tree:variable)} export.
+ *
  * @privateRemarks
  * Due to limitations of API-Extractor link resolution, this type can't be moved into internalTypes but should be considered just an implementation detail of the `Tree` export.
  *
@@ -75,14 +81,19 @@ 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}.
 	 */
 	parent(node: TreeNode): TreeNode | undefined;
 
 	/**
 	 * The key of the given node under its parent.
+	 *
 	 * @remarks
 	 * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).
 	 * Otherwise, this returns the key of the field that it is under (a `string`).
+	 *
+	 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.
 	 */
 	key(node: TreeNode): string | number;
 
@@ -126,7 +137,7 @@ export interface TreeNodeApi {
 }
 
 /**
- * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
+ * {@inheritDoc TreeNodeApi}
  */
 export const treeNodeApi: TreeNodeApi = {
 	parent(node: TreeNode): TreeNode | undefined {
@@ -303,29 +314,39 @@ export function getIdentifierFromNode(
 			return undefined;
 		case 1: {
 			const key = identifierFieldKeys[0] ?? oob();
-			const identifier = flexNode.tryGetField(key)?.boxedAt(0);
-			if (flexNode instanceof UnhydratedFlexTreeNode) {
-				if (identifier === undefined) {
-					return lazilyAllocateIdentifier(flexNode, key);
-				}
-				return identifier.value as string;
-			}
-			assert(
-				identifier?.context.isHydrated() === true,
-				0xa27 /* Expected hydrated identifier */,
-			);
-			const identifierValue = identifier.value as string;
+			const identifierField = flexNode.tryGetField(key);
+			assert(identifierField !== undefined, 0xbb5 /* missing identifier field */);
+			const identifierValue = getTreeNodeForField(identifierField);
+			assert(typeof identifierValue === "string", 0xbb6 /* identifier not a string */);
 
-			if (compression === "preferCompressed") {
-				const localNodeKey =
-					identifier.context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
-				return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;
-			} else if (compression === "compressed") {
-				const localNodeKey =
-					identifier.context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
-				return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : undefined;
+			const context = flexNode.context;
+			switch (compression) {
+				case "preferCompressed": {
+					if (context.isHydrated()) {
+						const localNodeKey =
+							context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
+						return localNodeKey !== undefined
+							? extractFromOpaque(localNodeKey)
+							: identifierValue;
+					} else {
+						return identifierValue;
+					}
+				}
+				case "compressed": {
+					if (context.isHydrated()) {
+						const localNodeKey =
+							context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
+						return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : undefined;
+					} else {
+						return undefined;
+					}
+				}
+				case "uncompressed": {
+					return identifierValue;
+				}
+				default:
+					unreachableCase(compression);
 			}
-			return identifierValue;
 		}
 		default:
 			throw new UsageError(

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

@@ -6,6 +6,7 @@
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { assert, fail } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	aboveRootPlaceholder,
@@ -14,7 +15,6 @@ import {
 	type FieldKey,
 	type ITreeCursor,
 	type ITreeCursorSynchronous,
-	type TreeNodeSchemaIdentifier,
 } from "../../core/index.js";
 import { brand } from "../../util/index.js";
 import type {
@@ -40,6 +40,7 @@ import { isObjectNodeSchema } from "../node-kinds/index.js";
 import {
 	customFromCursor,
 	replaceHandles,
+	unknownTypeError,
 	type CustomTreeNode,
 	type HandleConverter,
 	type SchemalessParseOptions,
@@ -153,12 +154,14 @@ export function applySchemaToParserOptions(
 						return key;
 					},
 					parse: (type, inputKey): FieldKey => {
-						const simpleNodeSchema =
-							context.schema.get(brand(type)) ?? fail(0xb3a /* missing schema */);
+						const simpleNodeSchema = context.schema.get(brand(type)) ?? unknownTypeError(type);
 						if (isObjectNodeSchema(simpleNodeSchema)) {
-							const info =
-								simpleNodeSchema.flexKeyMap.get(inputKey) ??
-								fail(0xb3b /* missing field info */);
+							const info = simpleNodeSchema.flexKeyMap.get(inputKey);
+							if (info === undefined) {
+								throw new UsageError(
+									`Failed to parse VerboseTree due to unexpected key ${JSON.stringify(inputKey)} on type ${JSON.stringify(type)}.`,
+								);
+							}
 							return info.storedKey;
 						}
 						return brand(inputKey);
@@ -203,19 +206,19 @@ function verboseTreeAdapter(options: SchemalessParseOptions): CursorAdapter<Verb
 		type: (node: VerboseTree) => {
 			switch (typeof node) {
 				case "number":
-					return numberSchema.identifier as TreeNodeSchemaIdentifier;
+					return brand(numberSchema.identifier);
 				case "string":
-					return stringSchema.identifier as TreeNodeSchemaIdentifier;
+					return brand(stringSchema.identifier);
 				case "boolean":
-					return booleanSchema.identifier as TreeNodeSchemaIdentifier;
+					return brand(booleanSchema.identifier);
 				default:
 					if (node === null) {
-						return nullSchema.identifier as TreeNodeSchemaIdentifier;
+						return brand(nullSchema.identifier);
 					}
 					if (isFluidHandle(node)) {
-						return handleSchema.identifier as TreeNodeSchemaIdentifier;
+						return brand(handleSchema.identifier);
 					}
-					return node.type as TreeNodeSchemaIdentifier;
+					return brand(node.type);
 			}
 		},
 		keysFromNode: (node: VerboseTree): readonly FieldKey[] => {