@fluidframework/tree 2.51.0 → 2.53.0-350190

package/src/shared-tree/treeAlpha.ts

@@ -36,7 +36,6 @@ import {
 	verboseFromCursor,
 	type TreeEncodingOptions,
 	type VerboseTree,
-	toStoredSchema,
 	extractPersistedSchema,
 	type TreeBranch,
 	TreeViewConfigurationAlpha,
@@ -51,6 +50,10 @@ import {
 	NodeKind,
 	tryGetTreeNodeForField,
 	isObjectNodeSchema,
+	isTreeNode,
+	toInitialSchema,
+	convertField,
+	toUnhydratedSchema,
 } from "../simple-tree/index.js";
 import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import {
@@ -191,11 +194,19 @@ export interface TreeIdentifierUtils {
  * Extensions to {@link (Tree:interface)} and {@link (TreeBeta:interface)} which are not yet stable.
  * @remarks
  * Use via the {@link (TreeAlpha:variable)} singleton.
+ *
+ * The unhydrated node creation APIs in this interface do not support {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields | unknown optional fields}.
+ * This is because unknown optional fields still must have a schema: its just that the schema may come from the document's stored schema.
+ * Unhydrated nodes created via this interface are not associated with any document, so there is nowhere for them to get schema for unknown optional fields.
+ * Note that {@link (TreeBeta:interface).clone} can create an unhydrated node with unknown optional fields, as it uses the source node's stored schema (if any).
+ *
+ * Export APIs in this interface include {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields | unknown optional fields}
+ * if they are using {@link TreeEncodingOptions.useStoredKeys | stored keys}.
+ *
  * @privateRemarks
- * TODO: AB#43548:
- * How all the create and all the import and export APIs handle unknown optional fields needs to be figured out, tested and documented.
- * This will need to be extended/generalized to cover other future schema evolution options as well once they exist.
- * See also TreeBeta.clone with a similar issue.
+ * TODO:
+ * There should be a way to provide a source for defaulted identifiers for unhydrated node creation, either via these APIs or some way to add them to its output later.
+ * If an option were added to these APIs, it could also be used to enable unknown optional fields.
  *
  * @system @sealed @alpha
  */
@@ -219,8 +230,6 @@ export interface TreeAlpha {
 	 * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.
 	 * This function exists as a generalization that can be used in other cases as well,
 	 * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.
-	 * @privateRemarks
-	 * TODO: AB#43548: There should be a way to provide a source for defaulted identifiers, either via this API or some way to add them to its output later.
 	 */
 	create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(
 		schema: UnsafeUnknownSchema extends TSchema
@@ -263,6 +272,14 @@ export interface TreeAlpha {
 	 * Construct tree content compatible with a field defined by the provided `schema`.
 	 * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
 	 * @param data - The data used to construct the field content. See {@link (TreeAlpha:interface).(exportVerbose:1)}.
+	 * @remarks
+	 * This currently does not support input containing {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields| unknown optional fields}.
+	 * @privateRemarks
+	 * See TODOs in {@link TreeEncodingOptions}.
+	 *
+	 * TODO: clarify how this handles out of schema data.
+	 * Does it robustly validate? How do you use it with schema evolution features like staged allowed types and allowUnknownOptionalFields? Which errors are deferred until insertion/hydration?
+	 * Ensure whatever policy is chosen is documented, enforces, tested and applied consistently to all import code paths.
 	 */
 	importVerbose<const TSchema extends ImplicitFieldSchema>(
 		schema: TSchema,
@@ -478,20 +495,24 @@ export const TreeAlpha: TreeAlpha = {
 			return undefined as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 		}
 		const cursor = cursorFromVerbose(data, schemalessConfig);
-		return createFromCursor(schema, cursor);
+		return createFromCursor(
+			schema,
+			cursor,
+			convertField(normalizeFieldSchema(schema), toUnhydratedSchema),
+		);
 	},
 
 	exportConcise,
 
 	exportVerbose(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): VerboseTree {
+		if (isTreeValue(node)) {
+			return node;
+		}
 		const config: TreeEncodingOptions = { ...options };
 
 		const cursor = borrowCursorFromTreeNodeOrValue(node);
-		return verboseFromCursor(
-			cursor,
-			tryGetSchema(node) ?? fail(0xace /* invalid input */),
-			config,
-		);
+		const kernel = getKernel(node);
+		return verboseFromCursor(cursor, kernel.context, config);
 	},
 
 	exportCompressed(
@@ -508,11 +529,18 @@ export const TreeAlpha: TreeAlpha = {
 		const batch: FieldBatch = [cursor];
 		// If none provided, create a compressor which will not compress anything.
 		const idCompressor = options.idCompressor ?? createIdCompressor();
+
+		// Grabbing an existing stored schema from the node is important to ensure that unknown optional fields can be preserved.
+		// Note that if the node is unhydrated, this can result in all staged allowed types being included in the schema, which might be undesired.
+		const storedSchema = isTreeNode(node)
+			? getKernel(node).context.flexContext.schema
+			: toInitialSchema(schema);
+
 		const context: FieldBatchEncodingContext = {
 			encodeType: TreeCompressionStrategy.Compressed,
 			idCompressor,
 			originatorId: idCompressor.localSessionId, // TODO: Why is this needed?
-			schema: { schema: toStoredSchema(schema), policy: defaultSchemaPolicy },
+			schema: { schema: storedSchema, policy: defaultSchemaPolicy },
 		};
 		const result = codec.encode(batch, context);
 		return result;
@@ -528,7 +556,8 @@ export const TreeAlpha: TreeAlpha = {
 		const config = new TreeViewConfigurationAlpha({ schema });
 		const content: ViewContent = {
 			// Always use a v1 schema codec for consistency.
-			schema: extractPersistedSchema(config, FluidClientVersion.v2_0),
+			// TODO: reevaluate how staged schema should behave in schema import/export APIs before stabilizing this.
+			schema: extractPersistedSchema(config.schema, FluidClientVersion.v2_0, () => true),
 			tree: compressedData,
 			idCompressor: options.idCompressor ?? createIdCompressor(),
 		};
@@ -701,17 +730,14 @@ function exportConcise(
 	node: TreeNode | TreeLeafValue | undefined,
 	options?: TreeEncodingOptions,
 ): ConciseTree | undefined {
-	if (node === undefined) {
-		return undefined;
+	if (!isTreeNode(node)) {
+		return node;
 	}
 	const config: TreeEncodingOptions = { ...options };
 
+	const kernel = getKernel(node);
 	const cursor = borrowCursorFromTreeNodeOrValue(node);
-	return conciseFromCursor(
-		cursor,
-		tryGetSchema(node) ?? fail(0xacd /* invalid input */),
-		config,
-	);
+	return conciseFromCursor(cursor, kernel.context, config);
 }
 
 /**

package/src/shared-tree/treeCheckout.ts

@@ -4,7 +4,7 @@
  */
 
 import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
-import type { Listenable } from "@fluidframework/core-interfaces/internal";
+import type { IFluidHandle, Listenable } from "@fluidframework/core-interfaces/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 import {
@@ -42,6 +42,11 @@ import {
 	type RevertibleAlpha,
 	type GraphCommit,
 	isAncestor,
+	moveToDetachedField,
+	type ITreeCursor,
+	type TreeNodeSchemaIdentifier,
+	type TreeNodeStoredSchema,
+	LeafNodeStoredSchema,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -68,15 +73,19 @@ import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamil
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import type { IDisposable } from "@fluidframework/core-interfaces";
-import type {
-	ImplicitFieldSchema,
-	ReadSchema,
-	TreeView,
-	TreeViewConfiguration,
-	UnsafeUnknownSchema,
-	ViewableTree,
-	TreeBranch,
-	TreeChangeEvents,
+import {
+	type ImplicitFieldSchema,
+	type ReadSchema,
+	type TreeView,
+	type TreeViewConfiguration,
+	type UnsafeUnknownSchema,
+	type ViewableTree,
+	type TreeBranch,
+	type TreeChangeEvents,
+	type VerboseTree,
+	customFromCursorStored,
+	type CustomTreeValue,
+	type CustomTreeNode,
 } from "../simple-tree/index.js";
 import { getCheckout, SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 
@@ -495,6 +504,24 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		this.#transaction.activeBranchEvents.on("ancestryTrimmed", this.onAncestryTrimmed);
 	}
 
+	public exportVerbose(): VerboseTree | undefined {
+		const cursor = this.forest.allocateCursor("contentSnapshot");
+		try {
+			moveToDetachedField(this.forest, cursor);
+			const length = cursor.getFieldLength();
+			if (length === 0) {
+				return undefined;
+			} else if (length === 1) {
+				cursor.enterNode(0);
+				return verboseFromCursor(cursor, this.storedSchema.nodeSchema);
+			} else {
+				fail(0xac8 /* Invalid document root length */);
+			}
+		} finally {
+			cursor.free();
+		}
+	}
+
 	private readonly onAfterChange = (event: SharedTreeBranchChange<SharedTreeChange>): void => {
 		this.editLock.lock();
 		this.#events.emit("beforeBatch", event);
@@ -1110,3 +1137,20 @@ function trackForksForDisposal(checkout: TreeCheckout): () => void {
 		disposed = true;
 	};
 }
+
+function verboseFromCursor(
+	reader: ITreeCursor,
+	schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>,
+): VerboseTree {
+	const fields = customFromCursorStored(reader, schema, verboseFromCursor);
+	const nodeSchema =
+		schema.get(reader.type) ?? fail(0xac9 /* missing schema for type in cursor */);
+	if (nodeSchema instanceof LeafNodeStoredSchema) {
+		return fields as CustomTreeValue;
+	}
+
+	return {
+		type: reader.type,
+		fields: fields as CustomTreeNode<IFluidHandle>,
+	};
+}

package/src/shared-tree-core/branch.ts

@@ -251,12 +251,7 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 			// TODO: Pull this side effect out if/when more diverse ancestry walking helpers are available
 			if (c !== commit) {
 				const revision = this.mintRevisionTag();
-				const inverse = this.changeFamily.rebaser.changeRevision(
-					this.changeFamily.rebaser.invert(c, true, revision),
-					revision,
-					c.revision,
-				);
-
+				const inverse = this.changeFamily.rebaser.invert(c, true, revision);
 				inverses.push(tagRollbackInverse(inverse, revision, c.revision));
 				return false;
 			}

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

@@ -5,9 +5,8 @@
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 
-import type { ITreeCursor } from "../../core/index.js";
-import type { TreeNodeSchema, TreeLeafValue, ImplicitAllowedTypes } from "../core/index.js";
-import { getUnhydratedContext } from "../createContext.js";
+import type { ITreeCursor, TreeNodeStoredSchema } from "../../core/index.js";
+import type { TreeNodeSchema, TreeLeafValue, Context } from "../core/index.js";
 
 import {
 	customFromCursor,
@@ -43,7 +42,7 @@ export type ConciseTree<THandle = IFluidHandle> =
  */
 export function conciseFromCursor(
 	reader: ITreeCursor,
-	rootSchema: ImplicitAllowedTypes,
+	context: Context,
 	options: TreeEncodingOptions,
 ): ConciseTree {
 	const config: Required<TreeEncodingOptions> = {
@@ -51,16 +50,19 @@ export function conciseFromCursor(
 		...options,
 	};
 
-	const schemaMap = getUnhydratedContext(rootSchema).schema;
-	return conciseFromCursorInner(reader, config, schemaMap);
+	const storedSchemaMap = context.flexContext.schema.nodeSchema;
+	const schemaMap = context.schema;
+
+	return conciseFromCursorInner(reader, config, storedSchemaMap, schemaMap);
 }
 
 function conciseFromCursorInner(
 	reader: ITreeCursor,
 	options: Required<TreeEncodingOptions>,
+	storedSchema: ReadonlyMap<string, TreeNodeStoredSchema>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): ConciseTree {
-	return customFromCursor(reader, options, schema, conciseFromCursorInner);
+	return customFromCursor(reader, options, storedSchema, schema, conciseFromCursorInner);
 }
 
 /**

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

@@ -25,7 +25,11 @@ import {
 	evaluateLazySchema,
 	markSchemaMostDerived,
 } from "../core/index.js";
-import { toStoredSchema } from "../toStoredSchema.js";
+import {
+	permissiveStoredSchemaGenerationOptions,
+	restrictiveStoredSchemaGenerationOptions,
+	toStoredSchema,
+} from "../toStoredSchema.js";
 import {
 	isArrayNodeSchema,
 	isMapNodeSchema,
@@ -47,14 +51,20 @@ import type { SimpleNodeSchema, SimpleTreeSchema } from "../simpleSchema.js";
  */
 export interface ITreeConfigurationOptions {
 	/**
-	 * If `true`, the tree will validate new content against its stored schema at insertion time
+	 * If `true`, the tree will perform additional validation of content against its stored schema
 	 * and throw an error if the new content doesn't match the expected schema.
 	 *
 	 * @defaultValue `false`.
 	 *
-	 * @remarks Enabling schema validation has a performance penalty when inserting new content into the tree because
+	 * @remarks
+	 * Currently most cases already have some schema validation, so this is mainly for additional validation which may be useful when debugging issues,
+	 * working with untyped APIs, or when the small performance overhead is a non-issue.
+	 *
+	 * Enabling schema validation has a performance penalty when inserting new content into the tree because
 	 * additional checks are done. Enable this option only in scenarios where you are ok with that operation being a
 	 * bit slower.
+	 *
+	 * For additional validation in more cases, see {@link ForestTypeExpensiveDebug}.
 	 */
 	enableSchemaValidation?: boolean;
 
@@ -155,6 +165,9 @@ export interface ITreeViewConfiguration<
 
 /**
  * Configuration for {@link ViewableTree.viewWith}.
+ * @privateRemarks
+ * When `ImplicitAnnotatedFieldSchema` is stabilized, TSchema should be updated to use it.
+ * When doing this, the example for `staged` will need to be updated/simplified.
  * @sealed @public
  */
 export class TreeViewConfiguration<
@@ -207,7 +220,8 @@ export class TreeViewConfiguration<
 
 		// Eagerly perform this conversion to surface errors sooner.
 		// Includes detection of duplicate schema identifiers.
-		toStoredSchema(config.schema);
+		toStoredSchema(config.schema, restrictiveStoredSchemaGenerationOptions);
+		toStoredSchema(config.schema, permissiveStoredSchemaGenerationOptions);
 
 		const definitions = new Map<string, SimpleNodeSchema & TreeNodeSchema>();
 

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

@@ -4,65 +4,56 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	CursorLocationType,
+	forbiddenFieldKindIdentifier,
 	mapCursorField,
 	mapCursorFields,
 	type ITreeCursorSynchronous,
 	type SchemaAndPolicy,
+	type TreeFieldStoredSchema,
 } from "../../core/index.js";
 import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../fieldSchema.js";
 import {
 	type Context,
 	getOrCreateNodeFromInnerNode,
-	type NodeKind,
 	type Unhydrated,
 	UnhydratedFlexTreeNode,
 	createField,
 } from "../core/index.js";
 import {
 	defaultSchemaPolicy,
-	inSchemaOrThrow,
 	isFieldInSchema,
+	throwOutOfSchema,
 } from "../../feature-libraries/index.js";
 import { getUnhydratedContext } from "../createContext.js";
-import { createUnknownOptionalFieldPolicy } from "../node-kinds/index.js";
-import type { SimpleNodeSchema, SimpleNodeSchemaBase } from "../simpleSchema.js";
-import { getStoredSchema } from "../toStoredSchema.js";
 import { unknownTypeError } from "./customTree.js";
 
 /**
  * Creates an unhydrated simple-tree field from a cursor in nodes mode.
  * @remarks
- * Does not support defaults.
- * Validates the field is in schema.
- *
- * TODO: AB#43548: How this handles unknown optional fields needs to be figured out, tested and documented.
+ * Does not support providing missing defaults values.
+ * Validates the field is in schema using `destinationSchema` the provided `contextForNewNodes` or the default unhydrated context if not provided.
  */
 export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 	schema: TSchema,
 	cursor: ITreeCursorSynchronous | undefined,
+	destinationSchema: TreeFieldStoredSchema,
+	contextForNewNodes?: Context,
 ): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
-	const context = getUnhydratedContext(schema);
+	const context = contextForNewNodes ?? getUnhydratedContext(schema);
+	assert(context.flexContext.isHydrated() === false, 0xbfe /* Expected unhydrated context */);
 	const mapTrees = cursor === undefined ? [] : [unhydratedFlexTreeFromCursor(context, cursor)];
 
-	const flexSchema = context.flexContext.schema;
-
-	const schemaValidationPolicy: SchemaAndPolicy = {
-		policy: {
-			...defaultSchemaPolicy,
-			allowUnknownOptionalFields: createUnknownOptionalFieldPolicy(schema),
-		},
+	const schemaAndPolicy: SchemaAndPolicy = {
+		policy: defaultSchemaPolicy,
 		schema: context.flexContext.schema,
 	};
 
-	const maybeError = isFieldInSchema(
-		mapTrees,
-		flexSchema.rootFieldSchema,
-		schemaValidationPolicy,
-	);
-	inSchemaOrThrow(maybeError);
+	// Assuming the caller provides the correct `contextForNewNodes`, this should handle unknown optional fields.
+	isFieldInSchema(mapTrees, destinationSchema, schemaAndPolicy, throwOutOfSchema);
 
 	if (mapTrees.length === 0) {
 		return undefined as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
@@ -80,27 +71,44 @@ export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 /**
  * Construct an {@link UnhydratedFlexTreeNode} from a cursor in Nodes mode.
  * @remarks
- * This does not validate the node is in schema.
+ * This does not fully validate the node is in schema, but does throw UsageErrors for some cases of out-of-schema content.
+ *
+ * Does not support unknown optional fields: will throw a UsageError if the field is not in schema.
+ * This cannot easily be fixed as this code requires a schema for each subtree to process, and none is available for unknown optional fields.
  */
 export function unhydratedFlexTreeFromCursor(
 	context: Context,
 	cursor: ITreeCursorSynchronous,
 ): UnhydratedFlexTreeNode {
 	assert(cursor.mode === CursorLocationType.Nodes, 0xbb4 /* Expected nodes cursor */);
-	const schema = context.schema.get(cursor.type) ?? unknownTypeError(cursor.type);
-	const storedSchema = getStoredSchema(
-		schema as SimpleNodeSchemaBase<NodeKind> as SimpleNodeSchema,
-	);
+	const identifier = cursor.type;
+	const storedSchema =
+		context.flexContext.schema.nodeSchema.get(identifier) ?? unknownTypeError(identifier);
+
 	const fields = new Map(
-		mapCursorFields(cursor, () => [
-			cursor.getFieldKey(),
-			createField(
-				context.flexContext,
-				storedSchema.getFieldSchema(cursor.getFieldKey()).kind,
+		mapCursorFields(cursor, () => {
+			const fieldSchema = storedSchema.getFieldSchema(cursor.getFieldKey());
+			if (fieldSchema.kind === forbiddenFieldKindIdentifier) {
+				// Check for unexpected fields before recursing into children:
+				// Code which hits this case is very likely to also use an unknown type in the unexpected field, which would give a more confusing error message.
+				// This case is detected here to improve error quality.
+				// Also note that if using the view schema from above to suppress this error for unknownOptionalFields, that would not provide a way to handle unknown types in those fields:
+				// they would still error, but with that more confusing message about unknown types.
+				throw new UsageError(
+					// Using JSON.stringify to handle quoting and escaping since both key and identifier can technically contain quotes themselves.
+					`Field ${JSON.stringify(cursor.getFieldKey())} is not defined in the schema ${JSON.stringify(identifier)}.`,
+				);
+			}
+			return [
 				cursor.getFieldKey(),
-				mapCursorField(cursor, () => unhydratedFlexTreeFromCursor(context, cursor)),
-			),
-		]),
+				createField(
+					context.flexContext,
+					fieldSchema.kind,
+					cursor.getFieldKey(),
+					mapCursorField(cursor, () => unhydratedFlexTreeFromCursor(context, cursor)),
+				),
+			];
+		}),
 	);
 	return new UnhydratedFlexTreeNode(
 		{ type: cursor.type, value: cursor.value },

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

@@ -19,6 +19,7 @@ import {
 	type ITreeCursor,
 	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
+	type TreeTypeSet,
 } from "../../core/index.js";
 import { FieldKinds, valueSchemaAllows } from "../../feature-libraries/index.js";
 import { cloneWithReplacements } from "../../util/index.js";
@@ -30,7 +31,7 @@ import {
 	numberSchema,
 	stringSchema,
 } from "../leafNodeSchema.js";
-import { isArrayNodeSchema, isObjectNodeSchema } from "../node-kinds/index.js";
+import { isObjectNodeSchema } from "../node-kinds/index.js";
 
 /**
  * Options for how to interpret or encode a tree when schema information is available.
@@ -42,7 +43,15 @@ export interface TreeEncodingOptions {
 	 * If false, use the property keys.
 	 * @remarks
 	 * Has no effect on {@link NodeKind}s other than {@link NodeKind.Object}.
+	 *
+	 * {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields|Unknown optional field} will be omitted when using property keys.
 	 * @defaultValue false.
+	 * @privateRemarks
+	 * TODO AB#43548:
+	 * Replace this with an enum that provides three options:
+	 * - `usePropertyKeys`: use property keys. Supported for import and export.
+	 * - `allStoredKeys`: use stored keys, and include unknown optional fields. Supported for export only, at least for the short term.
+	 * - `knownStoredKeys`: use stored keys but do not include unknown optional fields. Supported for import and export.
 	 */
 	readonly useStoredKeys?: boolean;
 }
@@ -77,19 +86,31 @@ export type CustomTreeNode<TChild> = TChild[] | { [key: string]: TChild };
 
 /**
  * Builds an {@link CustomTree} from a cursor in Nodes mode.
+ *
+ * @param reader - The cursor to read from.
+ * @param options - Options for how to interpret the tree.
+ * @param storedSchema - Schema which the cursor must comply with.
+ * Must be be possible to map to a view schema (mainly that sequences can only occur in the special ArrayNode pattern).
+ * Must include even unknown optional fields.
+ * @param schema - View schema used to derive the property keys for fields when `options` selects them via {@link TreeEncodingOptions.useStoredKeys}.
+ * @param childHandler - Function to handle children of the cursor.
+ *
+ * @remarks
+ * This can handle unknown optional fields only because they are included in the `storedSchema` and `schema` is only needed when using property keys, which also skips unknown optional fields.
  */
 export function customFromCursor<TChild>(
 	reader: ITreeCursor,
 	options: Required<TreeEncodingOptions>,
+	storedSchema: ReadonlyMap<string, TreeNodeStoredSchema>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 	childHandler: (
 		reader: ITreeCursor,
 		options: Required<TreeEncodingOptions>,
+		storedSchema: ReadonlyMap<string, TreeNodeStoredSchema>,
 		schema: ReadonlyMap<string, TreeNodeSchema>,
 	) => TChild,
 ): CustomTree<TChild> {
 	const type = reader.type;
-	const nodeSchema = schema.get(type) ?? fail(0xb2e /* missing schema for type in cursor */);
 
 	switch (type) {
 		case numberSchema.identifier:
@@ -105,28 +126,44 @@ export function customFromCursor<TChild>(
 			return reader.value;
 		default: {
 			assert(reader.value === undefined, 0xa54 /* out of schema: unexpected value */);
-			if (isArrayNodeSchema(nodeSchema)) {
+			const nodeSchema =
+				storedSchema.get(type) ?? fail(0xb2e /* missing schema for type in cursor */);
+			const arrayTypes = tryStoredSchemaAsArray(nodeSchema);
+
+			if (arrayTypes !== undefined) {
 				const fields = inCursorField(reader, EmptyKey, () =>
-					mapCursorField(reader, () => childHandler(reader, options, schema)),
+					mapCursorField(reader, () => childHandler(reader, options, storedSchema, schema)),
 				);
 				return fields;
 			} else {
 				const fields: Record<string, TChild> = {};
 				forEachField(reader, () => {
-					const children = mapCursorField(reader, () => childHandler(reader, options, schema));
-					if (children.length === 1) {
-						const storedKey = reader.getFieldKey();
-						const key =
-							isObjectNodeSchema(nodeSchema) && !options.useStoredKeys
-								? (nodeSchema.storedKeyToPropertyKey.get(storedKey) ??
-									fail(0xb2f /* missing property key */))
-								: storedKey;
-						// Length is checked above.
-						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-						fields[key] = children[0]!;
+					assert(reader.getFieldLength() === 1, 0xa19 /* invalid children number */);
+					const storedKey = reader.getFieldKey();
+					let key: string;
+					if (!options.useStoredKeys) {
+						const viewSchema =
+							schema.get(type) ?? fail(0xbff /* missing schema for type in cursor */);
+						if (isObjectNodeSchema(viewSchema)) {
+							const propertyKey = viewSchema.storedKeyToPropertyKey.get(storedKey);
+							if (propertyKey === undefined) {
+								assert(
+									viewSchema.allowUnknownOptionalFields,
+									0xc00 /* found unknown field where not allowed */,
+								);
+								// Skip unknown optional fields when using property keys.
+								return;
+							}
+							key = propertyKey;
+						} else {
+							key = storedKey;
+						}
 					} else {
-						assert(children.length === 0, 0xa19 /* invalid children number */);
+						key = storedKey;
 					}
+					reader.enterNode(0);
+					fields[key] = childHandler(reader, options, storedSchema, schema);
+					reader.exitNode();
 				});
 				return fields;
 			}
@@ -181,16 +218,18 @@ export function customFromCursorStored<TChild>(
 }
 
 /**
- * Assumes `schema` corresponds to a simple-tree schema.
+ * Checks if `schema` could correspond to a simple-tree array node.
  * If it is an array schema, returns the allowed types for the array field.
  * Otherwise returns `undefined`.
+ * @remarks
+ * If the schema was defined by the public API, this will be accurate since there is no way to define an object node with a sequence field.
  */
-export function tryStoredSchemaAsArray(
-	schema: TreeNodeStoredSchema,
-): ReadonlySet<string> | undefined {
+export function tryStoredSchemaAsArray(schema: TreeNodeStoredSchema): TreeTypeSet | undefined {
 	if (schema instanceof ObjectNodeStoredSchema) {
 		const empty = schema.getFieldSchema(EmptyKey);
 		if (empty.kind === FieldKinds.sequence.identifier) {
+			// This assert can only be hit by schema created not using the public API surface.
+			// If at some point this case needs to be tolerated, it can be replaced by "return undefined"
 			assert(schema.objectNodeFields.size === 1, 0xa9f /* invalid schema */);
 			return empty.types;
 		}