@fluidframework/tree 2.41.0 → 2.43.0-343119

package/src/shared-tree/schematizingTreeView.ts

@@ -247,28 +247,7 @@ export class SchematizingSimpleTreeView<
 			constraintsOnRevert: boolean,
 			constraints: readonly TransactionConstraint[] = [],
 		): void => {
-			for (const constraint of constraints) {
-				switch (constraint.type) {
-					case "nodeInDocument": {
-						const node = getOrCreateInnerNode(constraint.node);
-						const nodeStatus = getKernel(constraint.node).getStatus();
-						if (nodeStatus !== TreeStatus.InDocument) {
-							const revertText = constraintsOnRevert ? " on revert" : "";
-							throw new UsageError(
-								`Attempted to add a "nodeInDocument" constraint${revertText}, but the node is not currently in the document. Node status: ${nodeStatus}`,
-							);
-						}
-						if (constraintsOnRevert) {
-							this.checkout.editor.addNodeExistsConstraintOnRevert(node.anchorNode);
-						} else {
-							this.checkout.editor.addNodeExistsConstraint(node.anchorNode);
-						}
-						break;
-					}
-					default:
-						unreachableCase(constraint.type);
-				}
-			}
+			addConstraintsToTransaction(this.checkout, constraintsOnRevert, constraints);
 		};
 
 		this.checkout.transaction.start();
@@ -520,3 +499,42 @@ export function requireSchema(
 
 	return view;
 }
+
+/**
+ * Adds constraints to a `checkout`'s pending transaction.
+ *
+ * @param checkout - The checkout's who's transaction will have the constraints added to it.
+ * @param constraintsOnRevert - If true, use {@link ISharedTreeEditor.addNodeExistsConstraintOnRevert}.
+ * @param constraints - The constraints to add to the transaction.
+ *
+ * @see {@link RunTransactionParams.preconditions}.
+ */
+export function addConstraintsToTransaction(
+	checkout: ITreeCheckout,
+	constraintsOnRevert: boolean,
+	constraints: readonly TransactionConstraint[] = [],
+): void {
+	for (const constraint of constraints) {
+		switch (constraint.type) {
+			case "nodeInDocument": {
+				const node = getOrCreateInnerNode(constraint.node);
+				const nodeStatus = getKernel(constraint.node).getStatus();
+				if (nodeStatus !== TreeStatus.InDocument) {
+					const revertText = constraintsOnRevert ? " on revert" : "";
+					throw new UsageError(
+						`Attempted to add a "nodeInDocument" constraint${revertText}, but the node is not currently in the document. Node status: ${nodeStatus}`,
+					);
+				}
+				assert(node.isHydrated(), "In document node must be hydrated.");
+				if (constraintsOnRevert) {
+					checkout.editor.addNodeExistsConstraintOnRevert(node.anchorNode);
+				} else {
+					checkout.editor.addNodeExistsConstraint(node.anchorNode);
+				}
+				break;
+			}
+			default:
+				unreachableCase(constraint.type);
+		}
+	}
+}

package/src/shared-tree/sharedTree.ts

@@ -21,7 +21,12 @@ import {
 	type ITelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 
-import { type ICodecOptions, noopValidator } from "../codec/index.js";
+import {
+	type CodecWriteOptions,
+	FluidClientVersion,
+	type ICodecOptions,
+	noopValidator,
+} from "../codec/index.js";
 import {
 	type FieldKey,
 	type GraphCommit,
@@ -59,7 +64,7 @@ import {
 	makeTreeChunker,
 } from "../feature-libraries/index.js";
 // eslint-disable-next-line import/no-internal-modules
-import type { Format } from "../feature-libraries/schema-index/index.js";
+import type { FormatV1 } from "../feature-libraries/schema-index/index.js";
 import {
 	type ClonableSchemaAndPolicy,
 	DefaultResubmitMachine,
@@ -87,12 +92,6 @@ import {
 	type ITreeAlpha,
 	type SimpleObjectFieldSchema,
 } from "../simple-tree/index.js";
-import {
-	type Breakable,
-	breakingClass,
-	type JsonCompatible,
-	throwIfBroken,
-} from "../util/index.js";
 
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import { SharedTreeReadonlyChangeEnricher } from "./sharedTreeChangeEnricher.js";
@@ -100,6 +99,12 @@ import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { type TreeCheckout, type BranchableTree, createTreeCheckout } from "./treeCheckout.js";
+import {
+	type Breakable,
+	breakingClass,
+	type JsonCompatible,
+	throwIfBroken,
+} from "../util/index.js";
 
 /**
  * Copy of data from an {@link ITreePrivate} at some point in time.
@@ -187,6 +192,10 @@ const formatVersionToTopLevelCodecVersions = new Map<number, ExplicitCodecVersio
 		4,
 		{ forest: 1, schema: 1, detachedFieldIndex: 1, editManager: 4, message: 4, fieldBatch: 1 },
 	],
+	[
+		5,
+		{ forest: 1, schema: 2, detachedFieldIndex: 1, editManager: 4, message: 4, fieldBatch: 1 },
+	],
 ]);
 
 function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
@@ -506,7 +515,7 @@ export function persistedToSimpleSchema(
 	options: ICodecOptions,
 ): SimpleTreeSchema {
 	const schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);
-	const stored = schemaCodec.decode(persisted as Format);
+	const stored = schemaCodec.decode(persisted as FormatV1);
 	return exportSimpleSchema(stored);
 }
 
@@ -567,6 +576,11 @@ export const SharedTreeFormatVersion = {
 	 * Requires \@fluidframework/tree \>= 2.0.0.
 	 */
 	v3: 3,
+
+	/**
+	 * Requires \@fluidframework/tree \>= 2.0.0.
+	 */
+	v5: 5,
 } as const;
 
 /**
@@ -585,9 +599,9 @@ export type SharedTreeFormatVersion = typeof SharedTreeFormatVersion;
 
 /**
  * Configuration options for SharedTree.
- * @alpha
+ * @alpha @input
  */
-export type SharedTreeOptions = Partial<ICodecOptions> &
+export type SharedTreeOptions = Partial<CodecWriteOptions> &
 	Partial<SharedTreeFormatOptions> &
 	ForestOptions;
 
@@ -702,6 +716,7 @@ export function buildConfiguredForest(
 
 export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	jsonValidator: noopValidator,
+	oldestCompatibleClient: FluidClientVersion.v2_0,
 	forest: ForestTypeReference,
 	treeEncodeType: TreeCompressionStrategy.Compressed,
 	formatVersion: SharedTreeFormatVersion.v3,
@@ -744,20 +759,35 @@ function exportSimpleFieldSchemaStored(schema: TreeFieldStoredSchema): SimpleFie
 		default:
 			fail(0xaca /* invalid field kind */);
 	}
-	return { kind, allowedTypesIdentifiers: schema.types, metadata: {} };
+	return {
+		kind,
+		allowedTypesIdentifiers: schema.types,
+		metadata: {},
+		persistedMetadata: schema.persistedMetadata,
+	};
 }
 
+/**
+ * Export a {@link SimpleNodeSchema} from a {@link TreeNodeStoredSchema}.
+ * @privateRemarks
+ * TODO: Persist node metadata once schema FormatV2 is supported.
+ */
 function exportSimpleNodeSchemaStored(schema: TreeNodeStoredSchema): SimpleNodeSchema {
 	const arrayTypes = tryStoredSchemaAsArray(schema);
 	if (arrayTypes !== undefined) {
-		return { kind: NodeKind.Array, allowedTypesIdentifiers: arrayTypes, metadata: {} };
+		return {
+			kind: NodeKind.Array,
+			allowedTypesIdentifiers: arrayTypes,
+			metadata: {},
+			persistedMetadata: schema.metadata,
+		};
 	}
 	if (schema instanceof ObjectNodeStoredSchema) {
 		const fields = new Map<FieldKey, SimpleObjectFieldSchema>();
 		for (const [storedKey, field] of schema.objectNodeFields) {
 			fields.set(storedKey, { ...exportSimpleFieldSchemaStored(field), storedKey });
 		}
-		return { kind: NodeKind.Object, fields, metadata: {} };
+		return { kind: NodeKind.Object, fields, metadata: {}, persistedMetadata: schema.metadata };
 	}
 	if (schema instanceof MapNodeStoredSchema) {
 		assert(
@@ -768,10 +798,16 @@ function exportSimpleNodeSchemaStored(schema: TreeNodeStoredSchema): SimpleNodeS
 			kind: NodeKind.Map,
 			allowedTypesIdentifiers: schema.mapFields.types,
 			metadata: {},
+			persistedMetadata: schema.metadata,
 		};
 	}
 	if (schema instanceof LeafNodeStoredSchema) {
-		return { kind: NodeKind.Leaf, leafKind: schema.leafValue, metadata: {} };
+		return {
+			kind: NodeKind.Leaf,
+			leafKind: schema.leafValue,
+			metadata: {},
+			persistedMetadata: schema.metadata,
+		};
 	}
 	fail(0xacb /* invalid schema kind */);
 }

package/src/shared-tree/tree.ts

@@ -3,10 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { TreeStatus } from "../feature-libraries/index.js";
 import {
 	type ImplicitFieldSchema,
 	type TreeNode,
@@ -19,7 +17,10 @@ import {
 } from "../simple-tree/index.js";
 
 import { getCheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
-import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+import {
+	addConstraintsToTransaction,
+	SchematizingSimpleTreeView,
+} from "./schematizingTreeView.js";
 import type { ITreeCheckout } from "./treeCheckout.js";
 
 /**
@@ -463,23 +464,7 @@ function runTransactionInCheckout<TResult>(
 	preconditions: readonly TransactionConstraint[],
 ): TResult | typeof rollback {
 	checkout.transaction.start();
-	for (const constraint of preconditions) {
-		switch (constraint.type) {
-			case "nodeInDocument": {
-				const node = getOrCreateInnerNode(constraint.node);
-				const nodeStatus = Tree.status(constraint.node);
-				if (nodeStatus !== TreeStatus.InDocument) {
-					throw new UsageError(
-						`Attempted to add a "nodeInDocument" constraint, but the node is not currently in the document. Node status: ${nodeStatus}`,
-					);
-				}
-				checkout.editor.addNodeExistsConstraint(node.anchorNode);
-				break;
-			}
-			default:
-				unreachableCase(constraint.type);
-		}
-	}
+	addConstraintsToTransaction(checkout, false, preconditions);
 
 	let result: ReturnType<typeof transaction>;
 	try {

package/src/shared-tree/treeAlpha.ts

@@ -38,10 +38,16 @@ import {
 	getPropertyKeyFromStoredKey,
 	treeNodeApi,
 	getIdentifierFromNode,
-	mapTreeFromNodeData,
+	unhydratedFlexTreeFromInsertable,
+	getOrCreateNodeFromInnerNode,
 } from "../simple-tree/index.js";
 import { extractFromOpaque, type JsonCompatible } from "../util/index.js";
-import { noopValidator, type FluidClientVersion, type ICodecOptions } from "../codec/index.js";
+import {
+	FluidClientVersion,
+	noopValidator,
+	type ICodecOptions,
+	type CodecWriteOptions,
+} from "../codec/index.js";
 import type { ITreeCursorSynchronous } from "../core/index.js";
 import {
 	cursorForMapTreeField,
@@ -57,8 +63,6 @@ import {
 } from "../feature-libraries/index.js";
 import { independentInitializedView, type ViewContent } from "./independentView.js";
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
-import { currentVersion } from "../codec/index.js";
-import { createFromMapTree } from "../simple-tree/index.js";
 
 const identifier: TreeIdentifierUtils = (node: TreeNode): string | undefined => {
 	const nodeIdentifier = getIdentifierFromNode(node, "uncompressed");
@@ -295,7 +299,10 @@ export interface TreeAlpha {
 	 */
 	exportCompressed(
 		tree: TreeNode | TreeLeafValue,
-		options: { oldestCompatibleClient: FluidClientVersion; idCompressor?: IIdCompressor },
+		options: { idCompressor?: IIdCompressor } & Pick<
+			CodecWriteOptions,
+			"oldestCompatibleClient"
+		>,
 	): JsonCompatible<IFluidHandle>;
 
 	/**
@@ -367,8 +374,11 @@ export const TreeAlpha: TreeAlpha = {
 			? TreeFieldFromImplicitField<TSchema>
 			: TreeNode | TreeLeafValue | undefined
 	> {
-		const mapTree = mapTreeFromNodeData(data as InsertableField<UnsafeUnknownSchema>, schema);
-		const result = mapTree === undefined ? undefined : createFromMapTree(schema, mapTree);
+		const mapTree = unhydratedFlexTreeFromInsertable(
+			data as InsertableField<UnsafeUnknownSchema>,
+			schema,
+		);
+		const result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);
 		return result as Unhydrated<
 			TSchema extends ImplicitFieldSchema
 				? TreeFieldFromImplicitField<TSchema>
@@ -426,10 +436,10 @@ export const TreeAlpha: TreeAlpha = {
 
 	exportCompressed(
 		node: TreeNode | TreeLeafValue,
-		options: {
-			oldestCompatibleClient: FluidClientVersion;
-			idCompressor?: IIdCompressor;
-		},
+		options: { idCompressor?: IIdCompressor } & Pick<
+			CodecWriteOptions,
+			"oldestCompatibleClient"
+		>,
 	): JsonCompatible<IFluidHandle> {
 		const schema = tryGetSchema(node) ?? fail(0xacf /* invalid input */);
 		const format = fluidVersionToFieldBatchCodecWriteVersion(options.oldestCompatibleClient);
@@ -457,7 +467,8 @@ export const TreeAlpha: TreeAlpha = {
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
 		const config = new TreeViewConfigurationAlpha({ schema });
 		const content: ViewContent = {
-			schema: extractPersistedSchema(config, currentVersion),
+			// Always use a v1 schema codec for consistency.
+			schema: extractPersistedSchema(config, FluidClientVersion.v2_0),
 			tree: compressedData,
 			idCompressor: options.idCompressor ?? createIdCompressor(),
 		};

package/src/shared-tree/treeCheckout.ts

@@ -11,7 +11,7 @@ import {
 	UsageError,
 	type ITelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
-import { noopValidator } from "../codec/index.js";
+import { FluidClientVersion, noopValidator } from "../codec/index.js";
 import {
 	type Anchor,
 	type AnchorLocator,
@@ -279,7 +279,10 @@ export function createTreeCheckout(
 	const breaker = args?.breaker ?? new Breakable("TreeCheckout");
 	const schema = args?.schema ?? new TreeStoredSchemaRepository();
 	const forest = args?.forest ?? buildForest(breaker, schema);
-	const defaultCodecOptions = { jsonValidator: noopValidator };
+	const defaultCodecOptions = {
+		jsonValidator: noopValidator,
+		oldestCompatibleClient: FluidClientVersion.v2_0,
+	};
 	const defaultFieldBatchVersion = 1;
 	const changeFamily =
 		args?.changeFamily ??
@@ -287,7 +290,7 @@ export function createTreeCheckout(
 			revisionTagCodec,
 			args?.fieldBatchCodec ??
 				makeFieldBatchCodec(defaultCodecOptions, defaultFieldBatchVersion),
-			{ jsonValidator: noopValidator },
+			defaultCodecOptions,
 			args?.chunkCompressionStrategy,
 			idCompressor,
 		);

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

@@ -8,6 +8,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type {
+	IExperimentalIncrementalSummaryContext,
 	ISummaryTreeWithStats,
 	ITelemetryContext,
 } from "@fluidframework/runtime-definitions/internal";
@@ -49,22 +50,14 @@ export class EditManagerSummarizer<TChangeset> implements Summarizable {
 		private readonly schemaAndPolicy?: SchemaAndPolicy,
 	) {}
 
-	public getAttachSummary(
-		stringify: SummaryElementStringifier,
-		fullTree?: boolean,
-		trackState?: boolean,
-		telemetryContext?: ITelemetryContext,
-	): ISummaryTreeWithStats {
-		return this.summarizeCore(stringify);
-	}
-
-	public async summarize(
-		stringify: SummaryElementStringifier,
-		fullTree?: boolean,
-		trackState?: boolean,
-		telemetryContext?: ITelemetryContext,
-	): Promise<ISummaryTreeWithStats> {
-		return this.summarizeCore(stringify);
+	public summarize(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+	}): ISummaryTreeWithStats {
+		return this.summarizeCore(props.stringify);
 	}
 
 	private summarizeCore(stringify: SummaryElementStringifier): ISummaryTreeWithStats {

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

@@ -212,20 +212,30 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		serializer: IFluidSerializer,
 		telemetryContext?: ITelemetryContext,
 		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
+		fullTree?: boolean,
 	): ISummaryTreeWithStats {
 		const builder = new SummaryTreeBuilder();
 		const summarizableBuilder = new SummaryTreeBuilder();
 		// Merge the summaries of all summarizables together under a single ISummaryTree
 		for (const s of this.summarizables) {
+			// Add the summarizable's path in the summary tree to the incremental summary context's
+			// summary path, so that the summarizable can use it to generate incremental summaries.
+			const childIncrementalSummaryContext =
+				incrementalSummaryContext === undefined
+					? undefined
+					: {
+							...incrementalSummaryContext,
+							summaryPath: `${incrementalSummaryContext.summaryPath}/${summarizablesTreeKey}/${s.key}`,
+						};
 			summarizableBuilder.addWithStats(
 				s.key,
-				s.getAttachSummary(
-					(contents) => serializer.stringify(contents, this.sharedObject.handle),
-					undefined,
-					undefined,
+				s.summarize({
+					stringify: (contents: unknown) =>
+						serializer.stringify(contents, this.sharedObject.handle),
+					fullTree,
 					telemetryContext,
-					incrementalSummaryContext,
-				),
+					incrementalSummaryContext: childIncrementalSummaryContext,
+				}),
 			);
 		}
 
@@ -434,28 +444,27 @@ export interface Summarizable {
 	 */
 	readonly key: string;
 
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).getAttachSummary}
-	 * @param stringify - Serializes the contents of the component (including {@link (IFluidHandle:interface)}s) for storage.
-	 */
-	getAttachSummary(
-		stringify: SummaryElementStringifier,
-		fullTree?: boolean,
-		trackState?: boolean,
-		telemetryContext?: ITelemetryContext,
-		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
-	): ISummaryTreeWithStats;
-
 	/**
 	 * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).summarize}
 	 * @param stringify - Serializes the contents of the component (including {@link (IFluidHandle:interface)}s) for storage.
+	 * @param fullTree - A flag indicating whether the attempt should generate a full
+	 * summary tree without any handles for unchanged subtrees. It should only be set to true when generating
+	 * a summary from the entire container. The default value is false.
+	 * @param trackState - An optimization for tracking state of objects across summaries. If the state
+	 * of an object did not change since last successful summary, an
+	 * {@link @fluidframework/protocol-definitions#ISummaryHandle} can be used
+	 * instead of re-summarizing it. If this is `false`, the expectation is that you should never
+	 * send an `ISummaryHandle`, since you are not expected to track state. The default value is true.
+	 * @param telemetryContext - See {@link @fluidframework/runtime-definitions#ITelemetryContext}.
+	 * @param incrementalSummaryContext - See {@link @fluidframework/runtime-definitions#IExperimentalIncrementalSummaryContext}.
 	 */
-	summarize(
-		stringify: SummaryElementStringifier,
-		fullTree?: boolean,
-		trackState?: boolean,
-		telemetryContext?: ITelemetryContext,
-	): Promise<ISummaryTreeWithStats>;
+	summarize(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+	}): ISummaryTreeWithStats;
 
 	/**
 	 * Allows the component to perform custom loading. The storage service is scoped to this component and therefore

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

@@ -107,8 +107,8 @@ export interface ITreeConfigurationOptions {
 	 *
 	 * To make this more permissive in the future we can:
 	 *
-	 * - Make toMapTree more permissive (ex: allow disambiguation based on leaf type)
-	 * - Update this check to more tightly match toMapTree
+	 * - Make unhydratedFlexTreeFromInsertable more permissive (ex: allow disambiguation based on leaf type)
+	 * - Update this check to more tightly match unhydratedFlexTreeFromInsertable
 	 * - Add options to help schema authors disambiguate their types, such as "constant fields" which are not persisted, and always have a constant value.
 	 *
 	 * The above examples exist in executable form in this files tests, and should be updated there then copied back here.
@@ -343,7 +343,7 @@ export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): v
 			// Allow using the type of the field to disambiguate, at least for leaf types.
 			// Add "constant" fields which can be used to disambiguate even more cases without adding persisted data: maybe make them optional in constructor?
 			// Consider separating unambiguous implicit construction format from constructor arguments at type level, allowing constructor to superset the implicit construction options (ex: optional constant fields).
-			// The policy here however must remain at least as conservative as shallowCompatibilityTest in src/simple-tree/toMapTree.ts.
+			// The policy here however must remain at least as conservative as shallowCompatibilityTest in src/simple-tree/unhydratedFlexTreeFromInsertable.ts.
 
 			errors.push(
 				`The required fields of ${JSON.stringify(schema.identifier)} are insufficient to differentiate it from the following types: ${formatTypes(possiblyAmbiguous)}. For objects to be considered unambiguous, each must have required fields that do not all occur on any other object in the union.`,

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

@@ -5,35 +5,46 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 
-import type {
-	ExclusiveMapTree,
-	ITreeCursorSynchronous,
-	SchemaAndPolicy,
+import {
+	CursorLocationType,
+	mapCursorField,
+	mapCursorFields,
+	type ITreeCursorSynchronous,
+	type SchemaAndPolicy,
 } from "../../core/index.js";
 import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../schemaTypes.js";
 import {
+	type Context,
 	getOrCreateNodeFromInnerNode,
-	UnhydratedFlexTreeNode,
+	type NodeKind,
 	type Unhydrated,
+	UnhydratedFlexTreeNode,
+	createField,
 } from "../core/index.js";
 import {
 	defaultSchemaPolicy,
 	inSchemaOrThrow,
-	mapTreeFromCursor,
 	isFieldInSchema,
 } 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.
  */
 export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 	schema: TSchema,
 	cursor: ITreeCursorSynchronous | undefined,
 ): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
-	const mapTrees = cursor === undefined ? [] : [mapTreeFromCursor(cursor)];
 	const context = getUnhydratedContext(schema);
+	const mapTrees = cursor === undefined ? [] : [unhydratedFlexTreeFromCursor(context, cursor)];
+
 	const flexSchema = context.flexContext.schema;
 
 	const schemaValidationPolicy: SchemaAndPolicy = {
@@ -58,21 +69,40 @@ export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 	// Length asserted above, so this is safe. This assert is done instead of checking for undefined after indexing to ensure a length greater than 1 also errors.
 	// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 	const mapTree = mapTrees[0]!;
-	return createFromMapTree(schema, mapTree);
+
+	return getOrCreateNodeFromInnerNode(mapTree) as Unhydrated<
+		TreeFieldFromImplicitField<TSchema>
+	>;
 }
 
 /**
- * Creates an unhydrated simple-tree field from an ExclusiveMapTree.
+ * Construct an {@link UnhydratedFlexTreeNode} from a cursor in Nodes mode.
+ * @remarks
+ * This does not validate the node is in schema.
  */
-export function createFromMapTree<const TSchema extends ImplicitFieldSchema>(
-	schema: TSchema,
-	mapTree: ExclusiveMapTree,
-): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
-	const mapTreeNode = UnhydratedFlexTreeNode.getOrCreate(
-		getUnhydratedContext(schema),
-		mapTree,
+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 fields = new Map(
+		mapCursorFields(cursor, () => [
+			cursor.getFieldKey(),
+			createField(
+				context.flexContext,
+				storedSchema.getFieldSchema(cursor.getFieldKey()).kind,
+				cursor.getFieldKey(),
+				mapCursorField(cursor, () => unhydratedFlexTreeFromCursor(context, cursor)),
+			),
+		]),
+	);
+	return new UnhydratedFlexTreeNode(
+		{ type: cursor.type, value: cursor.value },
+		fields,
+		context,
 	);
-
-	const result = getOrCreateNodeFromInnerNode(mapTreeNode);
-	return result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 }

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

@@ -6,6 +6,7 @@
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import { assert, fail } from "@fluidframework/core-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	EmptyKey,
@@ -231,3 +232,12 @@ export function replaceHandles<T>(tree: unknown, replacer: HandleConverter<T>):
 		}
 	});
 }
+
+/**
+ * Throws a `UsageError` indicating that a type is unknown in the current context.
+ */
+export function unknownTypeError(type: string): never {
+	throw new UsageError(
+		`Failed to parse tree due to occurrence of type ${JSON.stringify(type)} which is not defined in this context.`,
+	);
+}

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

@@ -52,10 +52,7 @@ export {
 	getPropertyKeyFromStoredKey,
 	getIdentifierFromNode,
 } from "./treeNodeApi.js";
-export {
-	createFromCursor,
-	createFromMapTree,
-} from "./create.js";
+export { createFromCursor } from "./create.js";
 export {
 	type JsonSchemaId,
 	type JsonSchemaType,

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

@@ -275,7 +275,7 @@ export class SchemaCompatibilityTester {
 				}
 			}
 
-			return { kind: original.kind, types };
+			return { kind: original.kind, types, persistedMetadata: undefined };
 		}
 		return original;
 	}