@fluidframework/tree 2.53.0 → 2.60.0

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

@@ -17,7 +17,7 @@ import {
 } from "../node-kinds/index.js";
 import {
 	defaultSchemaFactoryObjectOptions,
-	SchemaFactory,
+	scoped,
 	structuralName,
 	type NodeSchemaOptionsAlpha,
 	type SchemaFactoryObjectOptions,
@@ -46,6 +46,7 @@ import type {
 	TreeRecordNodeUnsafe,
 } from "./typesUnsafe.js";
 import type { SimpleObjectNodeSchema } from "../simpleSchema.js";
+import { SchemaFactoryBeta } from "./schemaFactoryBeta.js";
 
 // This import prevents a large number of type references in the API reports from showing up as *_2.
 /* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import/no-duplicates */
@@ -212,20 +213,14 @@ const schemaStaticsAlpha: SchemaStaticsAlpha = {
  *
  * @alpha
  * @privateRemarks
- *
- * Some private methods on `SchemaFactory` are intentionally duplicated here to avoid increasing their exposure to `protected`.
- * If we were to do so, they would be exposed on the public API surface of `SchemaFactory`.
+ * When building schema, when `options` is not provided, `TCustomMetadata` is inferred as `unknown`.
+ * If desired, this could be made to infer `undefined` instead by adding overloads for everything,
+ * but currently it is not worth the maintenance overhead as there is no use case which this is known to be helpful for.
  */
 export class SchemaFactoryAlpha<
 	out TScope extends string | undefined = string | undefined,
 	TName extends number | string = string,
-> extends SchemaFactory<TScope, TName> {
-	private scoped2<Name extends TName | string>(name: Name): ScopedSchemaName<TScope, Name> {
-		return (
-			this.scope === undefined ? `${name}` : `${this.scope}.${name}`
-		) as ScopedSchemaName<TScope, Name>;
-	}
-
+> extends SchemaFactoryBeta<TScope, TName> {
 	/**
 	 * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.
 	 *
@@ -255,7 +250,7 @@ export class SchemaFactoryAlpha<
 		readonly createFromInsertable: unknown;
 	} {
 		return objectSchema(
-			this.scoped2(name),
+			scoped<TScope, TName, Name>(this, name),
 			fields,
 			true,
 			options?.allowUnknownOptionalFields ??
@@ -410,7 +405,7 @@ export class SchemaFactoryAlpha<
 		options?: NodeSchemaOptionsAlpha<TCustomMetadata>,
 	): MapNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
 		return mapSchema(
-			this.scoped2(name),
+			scoped<TScope, TName, Name>(this, name),
 			allowedTypes,
 			true,
 			true,
@@ -440,7 +435,7 @@ export class SchemaFactoryAlpha<
 	}
 
 	/**
-	 * Define (and add to this library) a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.
+	 * Define a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.
 	 *
 	 * @param name - Unique identifier for this schema within this factory's scope.
 	 * @param allowedTypes - The types that may appear in the array.
@@ -461,7 +456,7 @@ export class SchemaFactoryAlpha<
 		options?: NodeSchemaOptionsAlpha<TCustomMetadata>,
 	): ArrayNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
 		return arraySchema(
-			this.scoped2(name),
+			scoped<TScope, TName, Name>(this, name),
 			allowedTypes,
 			true,
 			true,
@@ -628,23 +623,24 @@ export class SchemaFactoryAlpha<
 	}
 
 	/**
-	 * Define a {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.
+	 * Define a {@link TreeNodeSchema} for a {@link (TreeRecordNode:interface)}.
 	 *
 	 * @param name - Unique identifier for this schema within this factory's scope.
 	 *
 	 * @remarks
-	 * This is not intended to be used directly, use the overload of `array` which takes a name instead.
-	 * This is only public to work around a compiler limitation.
+	 * This is not intended to be used directly, use the overload of `record` which takes a name instead.
 	 */
 	private namedRecord<
 		Name extends TName | string,
 		const T extends ImplicitAllowedTypes,
 		const ImplicitlyConstructable extends boolean,
+		const TCustomMetadata = unknown,
 	>(
 		name: Name,
 		allowedTypes: T,
 		customizable: boolean,
 		implicitlyConstructable: ImplicitlyConstructable,
+		options?: NodeSchemaOptionsAlpha<TCustomMetadata>,
 	): TreeNodeSchemaBoth<
 		/* Name */ ScopedSchemaName<TScope, Name>,
 		/* Kind */ NodeKind.Record,
@@ -656,10 +652,12 @@ export class SchemaFactoryAlpha<
 		/* TConstructorExtra */ undefined
 	> {
 		const record = recordSchema({
-			identifier: this.scoped2(name),
+			identifier: scoped<TScope, TName, Name>(this, name),
 			info: allowedTypes,
 			customizable,
 			implicitlyConstructable,
+			metadata: options?.metadata,
+			persistedMetadata: options?.persistedMetadata,
 		});
 
 		return record as TreeNodeSchemaBoth<
@@ -696,7 +694,7 @@ export class SchemaFactoryAlpha<
 		options?: NodeSchemaOptionsAlpha<TCustomMetadata>,
 	): RecordNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
 		return recordSchema({
-			identifier: this.scoped2(name),
+			identifier: scoped<TScope, TName, Name>(this, name),
 			info: allowedTypes,
 			customizable: true,
 			implicitlyConstructable: true,
@@ -716,7 +714,8 @@ export class SchemaFactoryAlpha<
 	public recordRecursive<
 		Name extends TName,
 		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
-	>(name: Name, allowedTypes: T) {
+		const TCustomMetadata = unknown,
+	>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {
 		const RecordSchema = this.namedRecord(
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,
@@ -724,6 +723,7 @@ export class SchemaFactoryAlpha<
 			// Setting this to true seems to work ok currently, but not for other node kinds.
 			// Supporting this could be fragile and might break other future changes, so it's being kept as false for now.
 			/* implicitlyConstructable */ false,
+			options,
 		);
 
 		return RecordSchema as TreeNodeSchemaClass<
@@ -740,19 +740,18 @@ export class SchemaFactoryAlpha<
 			},
 			/* ImplicitlyConstructable */ false,
 			/* Info */ T,
-			/* TConstructorExtra */ undefined
+			/* TConstructorExtra */ undefined,
+			/* TCustomMetadata */ TCustomMetadata
 		>;
 	}
 
 	/**
-	 * Create a {@link SchemaFactory} with a {@link SchemaFactory.scope|scope} which is a combination of this factory's scope and the provided name.
-	 * @remarks
-	 * The main use-case for this is when creating a collection of related schema (for example using a function that creates multiple schema).
-	 * Creating such related schema using a sub-scope helps ensure they won't collide with other schema in the parent scope.
+	 * {@inheritDoc SchemaFactoryBeta.scopedFactory}
 	 */
-	public scopedFactory<const T extends TName, TNameInner extends number | string = string>(
-		name: T,
-	): SchemaFactoryAlpha<ScopedSchemaName<TScope, T>, TNameInner> {
-		return new SchemaFactoryAlpha(this.scoped2(name));
+	public scopedFactoryAlpha<
+		const T extends TName,
+		TNameInner extends number | string = string,
+	>(name: T): SchemaFactoryAlpha<ScopedSchemaName<TScope, T>, TNameInner> {
+		return new SchemaFactoryAlpha(scoped<TScope, TName, T>(this, name));
 	}
 }

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

@@ -0,0 +1,28 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { SchemaFactory, scoped, type ScopedSchemaName } from "./schemaFactory.js";
+
+/**
+ * {@link SchemaFactory} with additional beta APIs.
+ * @beta
+ * @privateRemarks
+ */
+export class SchemaFactoryBeta<
+	out TScope extends string | undefined = string | undefined,
+	TName extends number | string = string,
+> extends SchemaFactory<TScope, TName> {
+	/**
+	 * Create a {@link SchemaFactory} with a {@link SchemaFactory.scope|scope} which is a combination of this factory's scope and the provided name.
+	 * @remarks
+	 * The main use-case for this is when creating a collection of related schema (for example using a function that creates multiple schema).
+	 * Creating such related schema using a sub-scope helps ensure they won't collide with other schema in the parent scope.
+	 */
+	public scopedFactory<const T extends TName, TNameInner extends number | string = string>(
+		name: T,
+	): SchemaFactoryBeta<ScopedSchemaName<TScope, T>, TNameInner> {
+		return new SchemaFactoryBeta(scoped(this, name));
+	}
+}

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

@@ -37,6 +37,7 @@ import {
 	ObjectNodeSchema,
 } from "../node-kinds/index.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
+import { KeyEncodingOptions } from "./customTree.js";
 
 /**
  * Generates a JSON Schema representation from a simple tree schema.
@@ -45,8 +46,6 @@ import { LeafNodeSchema } from "../leafNodeSchema.js";
  *
  * This cannot handle the case where the root is undefined since undefined is not a concept in JSON.
  * This also cannot handle {@link SchemaStatics.handle} since they also are not supported in JSON.
- *
- * @internal
  */
 export function toJsonSchema(
 	schema: TreeSchema,
@@ -62,6 +61,7 @@ export function toJsonSchema(
 	// TODO: deduplicate field handling logic from convertObjectNodeSchema: at least include metadata's description.
 	// TODO: maybe account for consider schema.kind, or just take in ImplicitAllowedTypes
 	// TODO: handle case where allowedTypes is empty.
+	// TODO: handle staged types in a controllable way.
 	return hasSingle(allowedTypes)
 		? {
 				...allowedTypes[0],
@@ -160,7 +160,10 @@ export function convertObjectNodeSchema(
 	const properties: Record<string, JsonFieldSchema> = {};
 	const required: string[] = [];
 	for (const [propertyKey, fieldSchema] of schema.fields) {
-		const key = options.useStoredKeys ? fieldSchema.storedKey : propertyKey;
+		const key =
+			options.keys === KeyEncodingOptions.usePropertyKeys
+				? propertyKey
+				: fieldSchema.storedKey;
 		const allowedTypes: JsonSchemaRef[] = [];
 		for (const allowedType of fieldSchema.allowedTypesIdentifiers) {
 			allowedTypes.push(createSchemaRef(allowedType));
@@ -190,6 +193,7 @@ export function convertObjectNodeSchema(
 		_treeNodeSchemaKind: NodeKind.Object,
 		properties,
 		required,
+		// TODO: support unknown optional fields (only when using "allStoredKeys", and constrain the content to be in schema somehow)
 		additionalProperties: false,
 	};
 

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

@@ -113,6 +113,7 @@ export type TransactionResult =
 /**
  * The parameters for the {@link RunTransaction | RunTransaction} API.
  * @alpha
+ * @input
  */
 export interface RunTransactionParams {
 	/**

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

@@ -166,6 +166,81 @@ export interface TreeBranch extends IDisposable {
 	 */
 	rebaseOnto(branch: TreeBranch): void;
 
+	/**
+	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
+	 * @param transaction - The function to run as the body of the transaction.
+	 * It should return a status object of {@link TransactionCallbackStatus | TransactionCallbackStatus } type.
+	 * It includes a "rollback" property which may be returned as true at any point during the transaction. This will
+	 * abort the transaction and discard any changes it made so far.
+	 * "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
+	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
+	 * @returns A result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:
+	 *
+	 * - A "success" flag indicating whether the transaction was successful or not.
+	 * - The success or failure value as returned by the transaction function.
+	 *
+	 * @remarks
+	 * This API will throw an error if the constraints are not met or something unexpected happens.
+	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
+	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
+	 * However, using a transaction has the following additional consequences:
+	 *
+	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
+	 *
+	 * Local change events will be emitted for each change as the transaction is being applied.
+	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
+	 *
+	 * Nested transactions:
+	 * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
+	 *
+	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
+	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
+	 * for the outermost transaction which includes all inner transactions.
+	 * - Undo will undo the outermost transaction and all inner transactions.
+	 */
+	runTransaction<TSuccessValue, TFailureValue>(
+		transaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,
+		params?: RunTransactionParams,
+	): TransactionResultExt<TSuccessValue, TFailureValue>;
+	/**
+	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
+	 * @param transaction - The function to run as the body of the transaction. It may return the following:
+	 *
+	 * - Nothing to indicate that the body of the transaction has successfully run.
+	 * - A status object of {@link VoidTransactionCallbackStatus | VoidTransactionCallbackStatus } type. It includes a "rollback" property which
+	 * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so
+	 * far. "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
+	 *
+	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
+	 * @returns A result object of {@link TransactionResult | TransactionResult} type. It includes a "success" flag indicating whether the
+	 * transaction was successful or not.
+	 *
+	 * @remarks
+	 * This API will throw an error if the constraints are not met or something unexpected happens.
+	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
+	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
+	 * However, using a transaction has the following additional consequences:
+	 *
+	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
+	 *
+	 * Local change events will be emitted for each change as the transaction is being applied.
+	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
+	 *
+	 * Nested transactions:
+	 * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
+	 *
+	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
+	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
+	 * for the outermost transaction which includes all inner transactions.
+	 * - Undo will undo the outermost transaction and all inner transactions.
+	 */
+	runTransaction(
+		transaction: () => VoidTransactionCallbackStatus | void,
+		params?: RunTransactionParams,
+	): TransactionResult;
+
 	/**
 	 * Dispose of this branch, cleaning up any resources associated with it.
 	 * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.
@@ -279,87 +354,6 @@ export interface TreeViewAlpha<
 
 	// Override the base branch method to return a typed view rather than merely a branch.
 	fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>;
-
-	/**
-	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
-	 * @param transaction - The function to run as the body of the transaction.
-	 * It should return a status object of {@link TransactionCallbackStatus | TransactionCallbackStatus } type.
-	 * It includes a "rollback" property which may be returned as true at any point during the transaction. This will
-	 * abort the transaction and discard any changes it made so far.
-	 * "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
-	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
-	 * @returns A result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:
-	 *
-	 * - A "success" flag indicating whether the transaction was successful or not.
-	 *
-	 * - The success of failure value as returned by the transaction function.
-	 * @remarks
-	 * This API will throw an error if the constraints are not met or something unexpected happens.
-	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
-	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
-	 * However, using a transaction has the following additional consequences:
-	 *
-	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
-	 *
-	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
-	 *
-	 * Local change events will be emitted for each change as the transaction is being applied.
-	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
-	 *
-	 * Nested transactions:
-	 * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
-	 *
-	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
-	 *
-	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
-	 * for the outermost transaction which includes all inner transactions.
-	 *
-	 * - Undo will undo the outermost transaction and all inner transactions.
-	 */
-	runTransaction<TSuccessValue, TFailureValue>(
-		transaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,
-		params?: RunTransactionParams,
-	): TransactionResultExt<TSuccessValue, TFailureValue>;
-	/**
-	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
-	 * @param transaction - The function to run as the body of the transaction. It may return the following:
-	 *
-	 * - Nothing to indicate that the body of the transaction has successfully run.
-	 *
-	 * - A status object of {@link VoidTransactionCallbackStatus | VoidTransactionCallbackStatus } type. It includes a "rollback" property which
-	 * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so
-	 * far. "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
-	 *
-	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
-	 * @returns A result object of {@link TransactionResult | TransactionResult} type. It includes a "success" flag indicating whether the
-	 * transaction was successful or not.
-	 * @remarks
-	 * This API will throw an error if the constraints are not met or something unexpected happens.
-	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
-	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
-	 * However, using a transaction has the following additional consequences:
-	 *
-	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
-	 *
-	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
-	 *
-	 * Local change events will be emitted for each change as the transaction is being applied.
-	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
-	 *
-	 * Nested transactions:
-	 * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
-	 *
-	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
-	 *
-	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
-	 * for the outermost transaction which includes all inner transactions.
-	 *
-	 * - Undo will undo the outermost transaction and all inner transactions.
-	 */
-	runTransaction(
-		transaction: () => VoidTransactionCallbackStatus | void,
-		params?: RunTransactionParams,
-	): TransactionResult;
 }
 
 /**

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

@@ -37,6 +37,7 @@ import {
 import { isObjectNodeSchema } from "../node-kinds/index.js";
 import {
 	customFromCursor,
+	KeyEncodingOptions,
 	replaceHandles,
 	unknownTypeError,
 	type CustomTreeNode,
@@ -118,53 +119,55 @@ export function applySchemaToParserOptions(
 	options: TreeEncodingOptions,
 ): SchemalessParseOptions {
 	const config: Required<TreeEncodingOptions> = {
-		useStoredKeys: false,
+		keys: KeyEncodingOptions.usePropertyKeys,
 		...options,
 	};
 
 	const context = getUnhydratedContext(schema);
 
 	return {
-		keyConverter: config.useStoredKeys
-			? undefined
-			: {
-					encode: (type, key: FieldKey): string => {
-						// translate stored key into property key.
-						const simpleNodeSchema =
-							context.schema.get(brand(type)) ?? fail(0xb39 /* missing schema */);
-						if (isObjectNodeSchema(simpleNodeSchema)) {
-							const propertyKey = simpleNodeSchema.storedKeyToPropertyKey.get(key);
-							if (propertyKey !== undefined) {
-								return propertyKey;
-							}
-							// Looking up an out of schema key.
-							// This must point to a non-existent field.
-							// It's possible that the key, if we returned it unmodified, could point to some data
-							// (for example if looking up a key which is a stored key already when using property keys).
-							// Thus return an arbitrary key that was selected randomly, so should not exist on non-adversarial data:
-							const arbitrary = "arbitrary unused key: fe71614a-bf3e-43b3-b7b0-4cef39538e90";
-							assert(
-								!simpleNodeSchema.storedKeyToPropertyKey.has(brand(arbitrary)),
-								0xa13 /* arbitrarily selected unused key was actually used */,
-							);
-							return arbitrary;
-						}
-						return key;
-					},
-					parse: (type, inputKey): FieldKey => {
-						const simpleNodeSchema = context.schema.get(brand(type)) ?? unknownTypeError(type);
-						if (isObjectNodeSchema(simpleNodeSchema)) {
-							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)}.`,
+		keyConverter:
+			config.keys !== KeyEncodingOptions.usePropertyKeys
+				? undefined
+				: {
+						encode: (type, key: FieldKey): string => {
+							// translate stored key into property key.
+							const simpleNodeSchema =
+								context.schema.get(brand(type)) ?? fail(0xb39 /* missing schema */);
+							if (isObjectNodeSchema(simpleNodeSchema)) {
+								const propertyKey = simpleNodeSchema.storedKeyToPropertyKey.get(key);
+								if (propertyKey !== undefined) {
+									return propertyKey;
+								}
+								// Looking up an out of schema key.
+								// This must point to a non-existent field.
+								// It's possible that the key, if we returned it unmodified, could point to some data
+								// (for example if looking up a key which is a stored key already when using property keys).
+								// Thus return an arbitrary key that was selected randomly, so should not exist on non-adversarial data:
+								const arbitrary = "arbitrary unused key: fe71614a-bf3e-43b3-b7b0-4cef39538e90";
+								assert(
+									!simpleNodeSchema.storedKeyToPropertyKey.has(brand(arbitrary)),
+									0xa13 /* arbitrarily selected unused key was actually used */,
 								);
+								return arbitrary;
+							}
+							return key;
+						},
+						parse: (type, inputKey): FieldKey => {
+							const simpleNodeSchema =
+								context.schema.get(brand(type)) ?? unknownTypeError(type);
+							if (isObjectNodeSchema(simpleNodeSchema)) {
+								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 info.storedKey;
-						}
-						return brand(inputKey);
+							return brand(inputKey);
+						},
 					},
-				},
 	};
 }
 
@@ -284,7 +287,7 @@ export function verboseFromCursor(
 	options: TreeEncodingOptions,
 ): VerboseTree {
 	const config: Required<TreeEncodingOptions> = {
-		useStoredKeys: false,
+		keys: KeyEncodingOptions.usePropertyKeys,
 		...options,
 	};
 

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

@@ -25,6 +25,12 @@ export interface SimpleNodeSchemaBase<
 
 	/**
 	 * User-provided {@link NodeSchemaMetadata} for this schema.
+	 *
+	 * @remarks
+	 * Note: this metadata is not persisted nor made part of the collaborative state; it is strictly client-local.
+	 * Different clients in the same collaborative session may see different metadata for the same field.
+	 *
+	 * Set via {@link NodeSchemaOptions.metadata}.
 	 */
 	readonly metadata: NodeSchemaMetadata<TCustomMetadata>;
 }

package/src/simple-tree/fieldSchema.ts

@@ -187,7 +187,9 @@ export interface FieldProps<TCustomMetadata = unknown> {
 export interface FieldPropsAlpha<TCustomMetadata = unknown>
 	extends FieldProps<TCustomMetadata> {
 	/**
-	 * The persisted metadata for this schema element.
+	 * The persisted metadata for a field schema.
+	 * @remarks
+	 * Sets {@link SimpleFieldSchema.persistedMetadata}.
 	 */
 	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
@@ -428,9 +430,6 @@ export class FieldSchemaAlpha<
 	 */
 	public readonly allowedTypesMetadata: AllowedTypesMetadata;
 
-	/**
-	 * Persisted metadata for this field schema.
-	 */
 	public get persistedMetadata(): JsonCompatibleReadOnlyObject | undefined {
 		return this.propsAlpha?.persistedMetadata;
 	}

package/src/simple-tree/index.ts

@@ -70,6 +70,7 @@ export {
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
 	SchemaFactory,
+	SchemaFactoryBeta,
 	SchemaFactoryAlpha,
 	type SchemaFactoryObjectOptions,
 	type ScopedSchemaName,
@@ -161,6 +162,8 @@ export {
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
 	type SchemaStaticsAlpha,
+	KeyEncodingOptions,
+	type TreeParsingOptions,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -184,11 +184,10 @@ function createRecordNodeProxy(
 
 			const innerNode = getOrCreateInnerNode(proxy);
 			const field = innerNode.tryGetField(brand(key)) as FlexTreeOptionalField | undefined;
-			if (field === undefined) {
-				return false;
+			if (field !== undefined) {
+				field.editor.set(undefined, field.length === 0);
 			}
 
-			field.editor.set(undefined, field.length === 0);
 			return true;
 		},
 	});

package/src/simple-tree/simpleSchema.ts

@@ -26,6 +26,15 @@ export interface SimpleNodeSchemaBaseAlpha<
 > extends SimpleNodeSchemaBase<TNodeKind, TCustomMetadata> {
 	/**
 	 * Persisted metadata for this node schema.
+	 * @remarks
+	 * While this can be stored in the document, not all versions / configurations will do so.
+	 * Additionally, this is not part of {@link TreeView.compatibility|schema compatibility}, so different clients
+	 * (even within the same collaborative session) may see different `persistedMetadata` for the same node.
+	 * Specified using {@link NodeSchemaOptionsAlpha.persistedMetadata}.
+	 * @privateRemarks
+	 * How/when this gets updated in documents,
+	 * and how to read it from documents should be documented here when this feature is more mature and these questions have good answers.
+	 * If this does end up getting reflected in some compatibility value, that should also be documented.
 	 */
 	readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined;
 }
@@ -184,6 +193,9 @@ export interface SimpleFieldSchema {
 
 	/**
 	 * Persisted metadata for this field schema.
+	 * @remarks
+	 * Like {@link SimpleNodeSchemaBaseAlpha.persistedMetadata} but for fields.
+	 * Set via {@link FieldPropsAlpha.persistedMetadata}.
 	 */
 	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }

package/src/simple-tree/toStoredSchema.ts

@@ -161,9 +161,6 @@ export const convertFieldKind: ReadonlyMap<FieldKind, FlexFieldKind> = new Map<
  * Converts a {@link TreeNodeSchema} into a {@link TreeNodeStoredSchema}.
  * @privateRemarks
  * TODO: Persist node metadata once schema FormatV2 is supported.
- *
- * TODO: AB#43548: Using a stored schema for unhydrated flex trees does not handle schema evolution features like "allowUnknownOptionalFields".
- * Usage of this and the conversion which wrap it should be audited and reduced.
  */
 export function getStoredSchema(
 	schema: SimpleNodeSchema,