@fluidframework/tree 2.23.0-323641 → 2.23.0-325054

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

@@ -27,13 +27,13 @@ import {
 	type TreeFieldFromImplicitField,
 	type UnsafeUnknownSchema,
 	FieldKind,
+	markSchemaMostDerived,
 } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import { toStoredSchema } from "../toStoredSchema.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
 import { assert } from "@fluidframework/core-utils/internal";
 import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js";
-import { markSchemaMostDerived } from "./schemaFactory.js";
 import { fail, getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
@@ -280,7 +280,7 @@ export class TreeViewConfiguration<
 			// 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: markSchemaMostDerived,
+			node: (schema) => markSchemaMostDerived(schema, true),
 			allowedTypes(types): void {
 				if (config.preventAmbiguity) {
 					checkUnion(types, ambiguityErrors);
@@ -376,7 +376,7 @@ export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): v
 		// For each field of schema, remove schema from possiblyAmbiguous that do not have that field
 		for (const [key, field] of schema.fields) {
 			if (field.kind === FieldKind.Required) {
-				const withKey = allObjectKeys.get(key) ?? fail("missing schema");
+				const withKey = allObjectKeys.get(key) ?? fail(0xb35 /* missing schema */);
 				for (const candidate of possiblyAmbiguous) {
 					if (!withKey.has(candidate)) {
 						possiblyAmbiguous.delete(candidate);

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

@@ -7,13 +7,14 @@ import { assert, oob } from "@fluidframework/core-utils/internal";
 
 import { EmptyKey, rootFieldKey } from "../../core/index.js";
 import { type TreeStatus, isTreeValue, FieldKinds } from "../../feature-libraries/index.js";
-import { fail, extractFromOpaque, isReadonlyArray } from "../../util/index.js";
+import { fail, extractFromOpaque } from "../../util/index.js";
 import {
 	type TreeLeafValue,
 	type ImplicitFieldSchema,
 	FieldSchema,
 	type ImplicitAllowedTypes,
 	type TreeNodeFromImplicitAllowedTypes,
+	normalizeAllowedTypes,
 } from "../schemaTypes.js";
 import {
 	booleanSchema,
@@ -39,7 +40,6 @@ import {
 	getOrCreateInnerNode,
 } from "../core/index.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
-import { isLazy, type LazyItem } from "../flexList.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
@@ -174,7 +174,7 @@ export const treeNodeApi: TreeNodeApi = {
 								changedFields,
 								(field) =>
 									nodeSchema.storedKeyToPropertyKey.get(field) ??
-									fail("Could not find stored key in schema."),
+									fail(0xb36 /* Could not find stored key in schema. */),
 							),
 						);
 						listener({ changedProperties });
@@ -203,26 +203,18 @@ export const treeNodeApi: TreeNodeApi = {
 		value: unknown,
 		schema: TSchema,
 	): value is TreeNodeFromImplicitAllowedTypes<TSchema> {
+		// This "is" utility would return false if the provided schema is a base type of the actual schema.
+		// This could be confusing, and that case can only be hit when violating the rule that there is a single most derived schema that gets used (See documentation on TreeNodeSchemaClass).
+		// Therefore this uses markSchemaMostDerived to ensure an informative usage error is thrown in the case where a base type is used.
+
 		const actualSchema = tryGetSchema(value);
 		if (actualSchema === undefined) {
 			return false;
 		}
-		if (isReadonlyArray<LazyItem<TreeNodeSchema>>(schema)) {
-			for (const singleSchema of schema) {
-				const testSchema = isLazy(singleSchema) ? singleSchema() : singleSchema;
-				if (testSchema === actualSchema) {
-					return true;
-				}
-			}
-			return false;
-		} else {
-			// Linter is incorrect about this bering unnecessary: it does not compile without the type assertion.
-			// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-			return (schema as TreeNodeSchema) === actualSchema;
-		}
+		return normalizeAllowedTypes(schema).has(actualSchema);
 	},
 	schema(node: TreeNode | TreeLeafValue): TreeNodeSchema {
-		return tryGetSchema(node) ?? fail("Not a tree node");
+		return tryGetSchema(node) ?? fail(0xb37 /* Not a tree node */);
 	},
 	shortId(node: TreeNode): number | string | undefined {
 		const schema = node[typeSchemaSymbol];
@@ -341,7 +333,7 @@ function getPropertyKeyFromStoredKey(
 	}
 
 	if (fields[storedKey] === undefined) {
-		fail("Existing stored key should always map to a property key");
+		fail(0xb38 /* Existing stored key should always map to a property key */);
 	}
 
 	return storedKey;

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

@@ -8,6 +8,8 @@ import type { RestrictiveStringRecord, UnionToIntersection } from "../../util/in
 import type {
 	ApplyKind,
 	ApplyKindInput,
+	CustomizedSchemaTyping,
+	CustomTypes,
 	FieldKind,
 	FieldSchema,
 	ImplicitAllowedTypes,
@@ -25,6 +27,7 @@ import type {
 } from "../core/index.js";
 import type { TreeArrayNode } from "../arrayNode.js";
 import type { FlexListToUnion, LazyItem } from "../flexList.js";
+import type { ApplyKindAssignment } from "../objectNode.js";
 
 /*
  * TODO:
@@ -48,17 +51,168 @@ import type { FlexListToUnion, LazyItem } from "../flexList.js";
  */
 export type Unenforced<_DesiredExtendsConstraint> = unknown;
 
+/**
+ * {@link Unenforced} version of {@link customizeSchemaTyping} for use with recursive schema types.
+ *
+ * @remarks
+ * When using this API to modify a schema derived type such that the type is no longer recursive,
+ * or uses an externally defined type (which can be recursive), {@link customizeSchemaTyping} should be used instead for an improved developer experience.
+ * Additionally, in this case, none of the "unsafe" type variants should be needed: the whole schema (with runtime but not schema derived type recursion)
+ * should use the normal (not unsafe/recursive) APIs.
+ * @alpha
+ */
+export function customizeSchemaTypingUnsafe<TSchema extends Unenforced<ImplicitAllowedTypes>>(
+	schema: TSchema,
+): CustomizerUnsafe<TSchema> {
+	// This function just does type branding, and duplicating the typing here to avoid any would just make it harder to maintain not easier:
+	const f = (): any => schema;
+	return { simplified: f, simplifiedUnrestricted: f, custom: f };
+}
+
+/**
+ * {@link Unenforced} version of `Customizer`.
+ * @remarks
+ * This has fewer options than the safe version, but all options can still be expressed using the "custom" method.
+ * @sealed @public
+ */
+export interface CustomizerUnsafe<TSchema extends Unenforced<ImplicitAllowedTypes>> {
+	/**
+	 * Replace typing with a single substitute type which allowed types must implement.
+	 * @remarks
+	 * This is generally type safe for reading the tree, but allows instances of `T` other than those listed in the schema to be assigned,
+	 * which can be out of schema and err at runtime in the same way {@link CustomizerUnsafe.relaxed} does.
+	 * Until with {@link CustomizerUnsafe.relaxed}, implicit construction is disabled, meaning all nodes must be explicitly constructed (and thus implement `T`) before being inserted.
+	 */
+	simplified<
+		T extends (TreeNode | TreeLeafValue) & TreeNodeFromImplicitAllowedTypesUnsafe<TSchema>,
+	>(): CustomizedSchemaTyping<
+		TSchema,
+		{
+			input: T;
+			readWrite: T;
+			output: T;
+		}
+	>;
+
+	/**
+	 * The same as {@link CustomizerUnsafe} except that more T values are allowed, even ones not known to be implemented by `TSchema`.
+	 */
+	simplifiedUnrestricted<T extends TreeNode | TreeLeafValue>(): CustomizedSchemaTyping<
+		TSchema,
+		{
+			input: T;
+			readWrite: T;
+			output: T;
+		}
+	>;
+
+	/**
+	 * Fully arbitrary customization.
+	 * Provided types override existing types.
+	 * @remarks
+	 * This can express any of the customizations possible via other {@link CustomizerUnsafe} methods:
+	 * this API is however more verbose and can more easily be used to unsafe typing.
+	 */
+	custom<T extends Partial<CustomTypes>>(): CustomizedSchemaTyping<
+		TSchema,
+		Pick<CustomTypes, "readWrite" | "output"> & {
+			// Check if property is provided. This check is needed to early out missing values so if undefined is allowed,
+			// not providing the field doesn't overwrite the corresponding type with undefined.
+			// TODO: test this case
+			[Property in keyof CustomTypes]: Property extends keyof T
+				? T[Property] extends CustomTypes[Property]
+					? T[Property]
+					: GetTypesUnsafe<TSchema>[Property]
+				: GetTypesUnsafe<TSchema>[Property];
+		}
+	>;
+}
+
 /**
  * {@link Unenforced} version of `ObjectFromSchemaRecord`.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type ObjectFromSchemaRecordUnsafe<
 	T extends Unenforced<RestrictiveStringRecord<ImplicitFieldSchema>>,
-> = {
-	-readonly [Property in keyof T]: TreeFieldFromImplicitFieldUnsafe<T[Property]>;
-};
+> =
+	// Due to https://github.com/microsoft/TypeScript/issues/43826 we can not set the desired setter type.
+	// Attempts to implement this in the cleaner way ObjectFromSchemaRecord uses cause recursive types to fail to compile.
+	// Supporting explicit field schema wrapping CustomizedSchemaTyping here breaks compilation of recursive cases as well.
+	{
+		-readonly [Property in keyof T as [T[Property]] extends [
+			CustomizedSchemaTyping<
+				unknown,
+				{
+					readonly readWrite: never;
+					readonly input: unknown;
+					readonly output: TreeNode | TreeLeafValue;
+				}
+			>,
+		]
+			? never // Remove readWrite version for cases using CustomizedSchemaTyping to set readWrite to never.
+			: Property]: AssignableTreeFieldFromImplicitFieldUnsafe<T[Property]>;
+	} & {
+		readonly [Property in keyof T as [T[Property]] extends [
+			CustomizedSchemaTyping<
+				unknown,
+				{
+					readonly readWrite: never;
+					readonly input: unknown;
+					readonly output: TreeNode | TreeLeafValue;
+				}
+			>,
+		]
+			? // Inverse of the conditional above: only include readonly fields when not including the readWrite one. This is required to make recursive types compile.
+				Property
+			: never]: TreeFieldFromImplicitFieldUnsafe<T[Property]>;
+	};
+
+/**
+ * {@link Unenforced} version of `AssignableTreeFieldFromImplicitField`.
+ * @remarks
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @privateRemarks
+ * Recursive version doesn't remove setters when this is never, so this uses covariant not contravariant union handling.
+ * @system @public
+ */
+export type AssignableTreeFieldFromImplicitFieldUnsafe<
+	TSchema extends Unenforced<ImplicitFieldSchema>,
+> = TSchema extends FieldSchemaUnsafe<infer Kind, infer Types>
+	? ApplyKindAssignment<GetTypesUnsafe<Types>["readWrite"], Kind>
+	: GetTypesUnsafe<TSchema>["readWrite"];
+
+/**
+ * {@link Unenforced} version of `TypesUnsafe`.
+ * @remarks
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @public
+ */
+export type GetTypesUnsafe<TSchema extends Unenforced<ImplicitAllowedTypes>> = [
+	TSchema,
+] extends [CustomizedSchemaTyping<unknown, infer TCustom>]
+	? TCustom
+	: StrictTypesUnsafe<TSchema>;
+
+/**
+ * {@link Unenforced} version of `StrictTypes`.
+ * @remarks
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @public
+ */
+export interface StrictTypesUnsafe<
+	TSchema extends Unenforced<ImplicitAllowedTypes>,
+	TInput = DefaultInsertableTreeNodeFromImplicitAllowedTypesUnsafe<TSchema>,
+	TOutput = DefaultTreeNodeFromImplicitAllowedTypesUnsafe<TSchema>,
+> {
+	input: TInput;
+	// Partial mitigation setter limitations (removal of setters when TInput is never by setting this to never) breaks compilation if used here,
+	// so recursive objects end up allowing some unsafe assignments which will error at runtime.
+	// This unsafety occurs when schema types are not exact, so output types are generalized which results in setters being generalized (wince they get the same type) which is unsafe.
+	readWrite: TOutput; // TInput extends never ? never : TOutput;
+	output: TOutput;
+}
 
 /**
  * {@link Unenforced} version of {@link TreeNodeSchema}.
@@ -121,7 +275,7 @@ export interface TreeNodeSchemaNonClassUnsafe<
 /**
  * {@link Unenforced} version of {@link TreeObjectNode}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type TreeObjectNodeUnsafe<
@@ -132,7 +286,7 @@ export type TreeObjectNodeUnsafe<
 /**
  * {@link Unenforced} version of {@link TreeFieldFromImplicitField}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type TreeFieldFromImplicitFieldUnsafe<TSchema extends Unenforced<ImplicitFieldSchema>> =
@@ -153,11 +307,21 @@ export type AllowedTypesUnsafe = readonly LazyItem<TreeNodeSchemaUnsafe>[];
 /**
  * {@link Unenforced} version of {@link TreeNodeFromImplicitAllowedTypes}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type TreeNodeFromImplicitAllowedTypesUnsafe<
 	TSchema extends Unenforced<ImplicitAllowedTypes>,
+> = GetTypesUnsafe<TSchema>["output"];
+
+/**
+ * {@link Unenforced} version of {@link DefaultTreeNodeFromImplicitAllowedTypesUnsafe}.
+ * @remarks
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @public
+ */
+export type DefaultTreeNodeFromImplicitAllowedTypesUnsafe<
+	TSchema extends Unenforced<ImplicitAllowedTypes>,
 > = TSchema extends TreeNodeSchemaUnsafe
 	? NodeFromSchemaUnsafe<TSchema>
 	: TSchema extends AllowedTypesUnsafe
@@ -168,11 +332,22 @@ export type TreeNodeFromImplicitAllowedTypesUnsafe<
  * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<
 	TSchema extends Unenforced<ImplicitAllowedTypes>,
+> = GetTypesUnsafe<TSchema>["input"];
+
+/**
+ * {@link Unenforced} version of {@link DefaultInsertableTreeNodeFromImplicitAllowedTypes}.
+ * @see {@link Input}
+ * @remarks
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @public
+ */
+export type DefaultInsertableTreeNodeFromImplicitAllowedTypesUnsafe<
+	TSchema extends Unenforced<ImplicitAllowedTypes>,
 > = [TSchema] extends [TreeNodeSchemaUnsafe]
 	? InsertableTypedNodeUnsafe<TSchema>
 	: [TSchema] extends [AllowedTypesUnsafe]
@@ -197,7 +372,7 @@ export type InsertableTreeNodeFromAllowedTypesUnsafe<
  * {@link Unenforced} version of {@link InsertableTypedNode}.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @privateRemarks
  * TODO:
  * This is less strict than InsertableTypedNode when given non-exact schema to avoid compilation issues.
@@ -216,7 +391,7 @@ export type InsertableTypedNodeUnsafe<
 /**
  * {@link Unenforced} version of {@link NodeFromSchema}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type NodeFromSchemaUnsafe<T extends Unenforced<TreeNodeSchema>> =
@@ -225,7 +400,7 @@ export type NodeFromSchemaUnsafe<T extends Unenforced<TreeNodeSchema>> =
 /**
  * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =
@@ -234,7 +409,7 @@ export type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =
 /**
  * {@link Unenforced} version of {@link (TreeArrayNode:interface)}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @sealed @public
  */
 export interface TreeArrayNodeUnsafe<TAllowedTypes extends Unenforced<ImplicitAllowedTypes>>
@@ -247,7 +422,7 @@ export interface TreeArrayNodeUnsafe<TAllowedTypes extends Unenforced<ImplicitAl
 /**
  * {@link Unenforced} version of {@link TreeMapNode}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @sealed @public
  */
 export interface TreeMapNodeUnsafe<T extends Unenforced<ImplicitAllowedTypes>>
@@ -271,7 +446,7 @@ export interface TreeMapNodeUnsafe<T extends Unenforced<ImplicitAllowedTypes>>
  * Copy of TypeScript's ReadonlyMap, but with `TreeNodeFromImplicitAllowedTypesUnsafe<T>` inlined into it.
  * Using this instead of ReadonlyMap in TreeMapNodeUnsafe is necessary to make recursive map schema not generate compile errors in the d.ts files when exported.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @privateRemarks
  * This is the same as `ReadonlyMap<K, TreeNodeFromImplicitAllowedTypesUnsafe<T>>` (Checked in test),
  * except that it avoids the above mentioned compile error.
@@ -313,7 +488,7 @@ export interface ReadonlyMapInlined<K, T extends Unenforced<ImplicitAllowedTypes
 /**
  * {@link Unenforced} version of `FieldHasDefault`.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @sealed @public
  */
 export type FieldHasDefaultUnsafe<T extends Unenforced<ImplicitFieldSchema>> =
@@ -328,7 +503,7 @@ export type FieldHasDefaultUnsafe<T extends Unenforced<ImplicitFieldSchema>> =
  * {@link Unenforced} version of `InsertableObjectFromSchemaRecord`.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type InsertableObjectFromSchemaRecordUnsafe<
@@ -350,7 +525,7 @@ export type InsertableObjectFromSchemaRecordUnsafe<
  * {@link Unenforced} version of {@link InsertableTreeFieldFromImplicitField}.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type InsertableTreeFieldFromImplicitFieldUnsafe<
@@ -365,7 +540,7 @@ export type InsertableTreeFieldFromImplicitFieldUnsafe<
 /**
  * {@link Unenforced} version of {@link FieldSchema}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @public
  */
 export interface FieldSchemaUnsafe<

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

@@ -172,7 +172,8 @@ export function applySchemaToParserOptions<TCustom>(
 			: {
 					encode: (type, key: FieldKey): string => {
 						// translate stored key into property key.
-						const simpleNodeSchema = context.schema.get(brand(type)) ?? fail("missing schema");
+						const simpleNodeSchema =
+							context.schema.get(brand(type)) ?? fail(0xb39 /* missing schema */);
 						if (isObjectNodeSchema(simpleNodeSchema)) {
 							const propertyKey = simpleNodeSchema.storedKeyToPropertyKey.get(key);
 							if (propertyKey !== undefined) {
@@ -193,10 +194,12 @@ export function applySchemaToParserOptions<TCustom>(
 						return key;
 					},
 					parse: (type, inputKey): FieldKey => {
-						const simpleNodeSchema = context.schema.get(brand(type)) ?? fail("missing schema");
+						const simpleNodeSchema =
+							context.schema.get(brand(type)) ?? fail(0xb3a /* missing schema */);
 						if (isObjectNodeSchema(simpleNodeSchema)) {
 							const info =
-								simpleNodeSchema.flexKeyMap.get(inputKey) ?? fail("missing field info");
+								simpleNodeSchema.flexKeyMap.get(inputKey) ??
+								fail(0xb3b /* missing field info */);
 							return info.storedKey;
 						}
 						return brand(inputKey);
@@ -345,7 +348,8 @@ function verboseFromCursorInner<TCustom>(
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): VerboseTree<TCustom> {
 	const fields = customFromCursor(reader, options, schema, verboseFromCursorInner);
-	const nodeSchema = schema.get(reader.type) ?? fail("missing schema for type in cursor");
+	const nodeSchema =
+		schema.get(reader.type) ?? fail(0xb3c /* missing schema for type in cursor */);
 	if (nodeSchema.kind === NodeKind.Leaf) {
 		return fields as CustomTreeValue<TCustom>;
 	}

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

@@ -250,7 +250,7 @@ export class ViewSchema {
 					this.viewSchemaAsStored.nodeSchema.get(adapter.output),
 				)
 			) {
-				fail("tree adapter for stored adapter.output should not be never");
+				fail(0xb3d /* tree adapter for stored adapter.output should not be never */);
 			}
 		}
 

package/src/simple-tree/arrayNode.ts

@@ -858,7 +858,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	// Therefore it must include `length`,
 	// even though this "length" is never invoked (due to being shadowed by the proxy provided own property).
 	public get length(): number {
-		return fail("Proxy should intercept length");
+		return fail(0xadb /* Proxy should intercept length */);
 	}
 
 	public [Symbol.iterator](): IterableIterator<TreeNodeFromImplicitAllowedTypes<T>> {
@@ -1045,7 +1045,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			throw new UsageError(`Concurrent editing and iteration is not allowed.`);
 		}
 		for (let i = 0; i < this.length; i++) {
-			yield this.at(i) ?? fail("Index is out of bounds");
+			yield this.at(i) ?? fail(0xadc /* Index is out of bounds */);
 			if (initialLastUpdatedStamp !== kernel.generationNumber) {
 				throw new UsageError(`Concurrent editing and iteration is not allowed.`);
 			}

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

@@ -31,7 +31,8 @@ export function getOrCreateNodeFromInnerNode(flexNode: InnerNode): TreeNode | Tr
 		return cached;
 	}
 
-	const classSchema = getSimpleNodeSchemaFromInnerNode(flexNode) ?? fail("Missing schema");
+	const classSchema =
+		getSimpleNodeSchemaFromInnerNode(flexNode) ?? fail(0xb3e /* Missing schema */);
 	const node = flexNode as unknown as InternalTreeNode;
 	// eslint-disable-next-line unicorn/prefer-ternary
 	if (typeof classSchema === "function") {

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

@@ -17,7 +17,7 @@ import { SimpleContextSlot, type Context } from "./context.js";
  */
 export function getSimpleNodeSchemaFromInnerNode(innerNode: InnerNode): TreeNodeSchema {
 	const context: Context = getSimpleContextFromInnerNode(innerNode);
-	return context.schema.get(innerNode.schema) ?? fail("missing schema from context");
+	return context.schema.get(innerNode.schema) ?? fail(0xb3f /* missing schema from context */);
 }
 
 /**

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

@@ -184,7 +184,7 @@ export class TreeNodeKernel {
 			// This can't be cached on this.#hydrated during hydration since initial tree is hydrated before the context is cached on the anchorSet.
 			return (
 				this.#hydrationState?.anchorNode.anchorSet.slots.get(SimpleContextSlot) ??
-				fail("missing simple-tree context")
+				fail(0xb40 /* missing simple-tree context */)
 			);
 		}
 		return this.initialContext;
@@ -303,7 +303,8 @@ export class TreeNodeKernel {
 			this.#hydrationState.innerNode = flexNode;
 		} else {
 			// ...otherwise, the flex node must be created
-			const context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail("missing context");
+			const context =
+				anchorNode.anchorSet.slots.get(ContextSlot) ?? fail(0xb41 /* missing context */);
 			const cursor = context.checkout.forest.allocateCursor("getFlexNode");
 			context.checkout.forest.moveCursorToPath(anchorNode, cursor);
 			this.#hydrationState.innerNode = makeTree(context, cursor);
@@ -332,7 +333,8 @@ export class TreeNodeKernel {
 	public anchorProxy(anchors: AnchorSet, path: UpPath): AnchorNode {
 		assert(!anchorForgetters.has(this.node), 0x91c /* Proxy anchor should not be set twice */);
 		const anchor = anchors.track(path);
-		const anchorNode = anchors.locate(anchor) ?? fail("Expected anchor node to be present");
+		const anchorNode =
+			anchors.locate(anchor) ?? fail(0xb42 /* Expected anchor node to be present */);
 		this.hydrate(anchorNode);
 		const forget = (): void => {
 			if (anchors.locate(anchor)) {
@@ -434,9 +436,9 @@ export function getTreeNodeSchemaFromHydratedFlexNode(flexNode: FlexTreeNode): T
 
 	const context =
 		flexNode.anchorNode.anchorSet.slots.get(SimpleContextSlot) ??
-		fail("Missing SimpleContextSlot");
+		fail(0xb43 /* Missing SimpleContextSlot */);
 
-	return context.schema.get(flexNode.schema) ?? fail("Missing schema");
+	return context.schema.get(flexNode.schema) ?? fail(0xb44 /* Missing schema */);
 }
 
 /**
@@ -461,7 +463,8 @@ function flexNodeFromAnchor(anchorNode: AnchorNode): FlexTreeNode {
 	if (flexNode !== undefined) {
 		return flexNode; // If it does have a flex node, return it...
 	} // ...otherwise, the flex node must be created
-	const context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail("missing context");
+	const context =
+		anchorNode.anchorSet.slots.get(ContextSlot) ?? fail(0xb45 /* missing context */);
 	const cursor = context.checkout.forest.allocateCursor("getFlexNode");
 	context.checkout.forest.moveCursorToPath(anchorNode, cursor);
 	const newFlexNode = makeTree(context, cursor);

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

@@ -79,7 +79,9 @@ export class UnhydratedFlexTreeNode implements UnhydratedFlexTreeNode {
 	}
 
 	public get storedSchema(): TreeNodeStoredSchema {
-		return this.context.schema.nodeSchema.get(this.mapTree.type) ?? fail("missing schema");
+		return (
+			this.context.schema.nodeSchema.get(this.mapTree.type) ?? fail(0xb46 /* missing schema */)
+		);
 	}
 
 	public readonly [flexTreeMarker] = FlexTreeEntityKind.Node as const;
@@ -215,7 +217,7 @@ export class UnhydratedFlexTreeNode implements UnhydratedFlexTreeNode {
 	public get anchorNode(): AnchorNode {
 		// This API is relevant to `LazyTreeNode`s, but not `UnhydratedFlexTreeNode`s.
 		// TODO: Refactor the FlexTreeNode interface so that stubbing this out isn't necessary.
-		return fail("UnhydratedFlexTreeNode does not implement anchorNode");
+		return fail(0xb47 /* UnhydratedFlexTreeNode does not implement anchorNode */);
 	}
 
 	private walkTree(): void {
@@ -294,10 +296,10 @@ const unparentedLocation: LocationInField = {
 		},
 		schema: brand(forbiddenFieldKindIdentifier),
 		get context(): never {
-			return fail("unsupported");
+			return fail(0xb48 /* unsupported */);
 		},
 		getFieldPath() {
-			fail("unsupported");
+			fail(0xb49 /* unsupported */);
 		},
 	},
 	index: -1,
@@ -489,7 +491,7 @@ export class UnhydratedTreeSequenceField
 			this.edit((mapTrees) => {
 				removed = mapTrees.splice(index, count);
 			});
-			return removed ?? fail("Expected removed to be set by edit");
+			return removed ?? fail(0xb4a /* Expected removed to be set by edit */);
 		},
 	};
 

package/src/simple-tree/flexList.ts

@@ -44,28 +44,18 @@ export function markEager<T>(t: T): T {
  * By default, items that are of type `"function"` will be considered lazy and all other items will be considered eager.
  * To force a `"function"` item to be treated as an eager item, call `markEager` before putting it in the list.
  * This is necessary e.g. when the eager list items are function types and the lazy items are functions that _return_ function types.
- * `FlexList`s are processed by `normalizeFlexList` and `normalizeFlexListEager`.
+ * Our one use of FlexList has some special normalization logic, see {@link normalizeAllowedTypes}.
  * @system @public
  */
 export type FlexList<Item = unknown> = readonly LazyItem<Item>[];
 
-/**
- * Given a `FlexList` of eager and lazy items, return an equivalent list where all items are eager.
- */
-export function normalizeFlexListEager<T>(t: FlexList<T>): T[] {
-	const data: T[] = t.map((value: LazyItem<T>) => {
-		if (isLazy(value)) {
-			return value();
-		}
-		return value;
-	});
-	return data;
-}
-
 /**
  * An "eager" or "lazy" Item in a `FlexList`.
  * Lazy items are wrapped in a function to allow referring to themselves before they are declared.
  * This makes recursive and co-recursive items possible.
+ * @privateRemarks
+ * `schemaTypes.ts`'s `evaluateLazySchema` (via {@link normalizeAllowedTypes})
+ * applies caching for the only current use of this type.
  * @public
  */
 export type LazyItem<Item = unknown> = Item | (() => Item);