@fluidframework/tree 2.41.0-337492 → 2.41.0-338186

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.41.0-337492",
+  "version": "2.41.0-338186",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -89,17 +89,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "2.41.0-337492",
-    "@fluidframework/container-runtime": "2.41.0-337492",
-    "@fluidframework/core-interfaces": "2.41.0-337492",
-    "@fluidframework/core-utils": "2.41.0-337492",
-    "@fluidframework/datastore-definitions": "2.41.0-337492",
-    "@fluidframework/driver-definitions": "2.41.0-337492",
-    "@fluidframework/id-compressor": "2.41.0-337492",
-    "@fluidframework/runtime-definitions": "2.41.0-337492",
-    "@fluidframework/runtime-utils": "2.41.0-337492",
-    "@fluidframework/shared-object-base": "2.41.0-337492",
-    "@fluidframework/telemetry-utils": "2.41.0-337492",
+    "@fluid-internal/client-utils": "2.41.0-338186",
+    "@fluidframework/container-runtime": "2.41.0-338186",
+    "@fluidframework/core-interfaces": "2.41.0-338186",
+    "@fluidframework/core-utils": "2.41.0-338186",
+    "@fluidframework/datastore-definitions": "2.41.0-338186",
+    "@fluidframework/driver-definitions": "2.41.0-338186",
+    "@fluidframework/id-compressor": "2.41.0-338186",
+    "@fluidframework/runtime-definitions": "2.41.0-338186",
+    "@fluidframework/runtime-utils": "2.41.0-338186",
+    "@fluidframework/shared-object-base": "2.41.0-338186",
+    "@fluidframework/telemetry-utils": "2.41.0-338186",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@types/ungap__structured-clone": "^1.2.0",
@@ -109,21 +109,21 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "2.41.0-337492",
-    "@fluid-private/stochastic-test-utils": "2.41.0-337492",
-    "@fluid-private/test-dds-utils": "2.41.0-337492",
-    "@fluid-private/test-drivers": "2.41.0-337492",
+    "@fluid-internal/mocha-test-setup": "2.41.0-338186",
+    "@fluid-private/stochastic-test-utils": "2.41.0-338186",
+    "@fluid-private/test-dds-utils": "2.41.0-338186",
+    "@fluid-private/test-drivers": "2.41.0-338186",
     "@fluid-tools/benchmark": "^0.51.0",
     "@fluid-tools/build-cli": "^0.55.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.55.0",
-    "@fluidframework/container-definitions": "2.41.0-337492",
-    "@fluidframework/container-loader": "2.41.0-337492",
+    "@fluidframework/container-definitions": "2.41.0-338186",
+    "@fluidframework/container-loader": "2.41.0-338186",
     "@fluidframework/eslint-config-fluid": "^5.7.3",
-    "@fluidframework/test-runtime-utils": "2.41.0-337492",
-    "@fluidframework/test-utils": "2.41.0-337492",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.33.0",
-    "@microsoft/api-extractor": "7.52.5",
+    "@fluidframework/test-runtime-utils": "2.41.0-338186",
+    "@fluidframework/test-utils": "2.41.0-338186",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.40.0",
+    "@microsoft/api-extractor": "7.52.8",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",
     "@types/mocha": "^10.0.10",
@@ -168,8 +168,8 @@
     "api": "fluid-build . --task api",
     "api-extractor:commonjs": "flub generate entrypoints --outDir ./dist",
     "api-extractor:esnext": "flub generate entrypoints --outDir ./lib --node10TypeCompat",
-    "bench": "mocha --timeout 999999 --perfMode --parentProcess --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js",
-    "bench:profile": "mocha --v8-prof --v8-logfile=profile.log --v8-no-logfile-per-isolate --timeout 999999 --perfMode --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js && node --prof-process profile.log > profile.txt && rimraf profile.log && echo See results in profile.txt",
+    "bench": "mocha --timeout 999999 --perfMode --parentProcess --fgrep @Benchmark --fgrep @ExecutionTime --reporter @fluid-tools/benchmark/dist/MochaReporter.js",
+    "bench:profile": "mocha --v8-prof --v8-logfile=profile.log --v8-no-logfile-per-isolate --timeout 999999 --perfMode --fgrep @Benchmark --fgrep @ExecutionTime --reporter @fluid-tools/benchmark/dist/MochaReporter.js && node --prof-process profile.log > profile.txt && rimraf profile.log && echo See results in profile.txt",
     "build": "fluid-build . --task build",
     "build:api-reports": "concurrently \"npm:build:api-reports:*\"",
     "build:api-reports:current": "api-extractor run --local --config api-extractor/api-extractor.current.json",
@@ -210,7 +210,7 @@
     "lint:fix": "fluid-build . --task eslint:fix --task format",
     "pack:tests": "tar -cf ./tree.test-files.tar ./src/test ./dist/test ./lib/test",
     "test": "npm run test:mocha",
-    "test:benchmark:report": "mocha --exit --perfMode --parentProcess --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js --timeout 60000",
+    "test:benchmark:report": "mocha --exit --perfMode --parentProcess --fgrep @Benchmark --fgrep @ExecutionTime --reporter @fluid-tools/benchmark/dist/MochaReporter.js --timeout 60000",
     "test:coverage": "c8 npm test",
     "test:customBenchmarks": "mocha --config ./.mocharc.customBenchmarks.cjs",
     "test:customBenchmarks:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:customBenchmarks",

package/src/feature-libraries/flex-tree/context.ts

@@ -79,6 +79,9 @@ export const ContextSlot = anchorSlot<Context>();
  * Implementation of `FlexTreeContext`.
  *
  * @remarks An editor is required to edit the FlexTree.
+ *
+ * A {@link FlexTreeContext} which is used to manage the cursors and anchors within the FlexTrees:
+ * This is necessary for supporting using this tree across edits to the forest, and not leaking memory.
  */
 export class Context implements FlexTreeHydratedContext, IDisposable {
 	public readonly withCursors: Set<LazyEntity> = new Set();
@@ -88,13 +91,19 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 	private disposed = false;
 
 	/**
-	 * @param flexSchema - Schema to use when working with the  tree.
-	 * @param checkout - The checkout.
-	 * @param nodeKeyManager - An object which handles node key generation and conversion
+	 * Stores the last accessed version of the root.
+	 * @remarks
+	 * Anything which can delete this field must clear it.
+	 * Currently "clear" is the only case.
 	 */
+	private lazyRootCache: FlexTreeField | undefined;
+
 	public constructor(
 		public readonly schemaPolicy: SchemaPolicy,
 		public readonly checkout: ITreeCheckout,
+		/**
+		 * An object which handles node key generation and conversion
+		 */
 		public readonly nodeKeyManager: NodeIdentifierManager,
 	) {
 		this.eventUnregister = [
@@ -158,16 +167,22 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 		for (const target of this.withAnchors) {
 			target[disposeSymbol]();
 		}
+		this.lazyRootCache = undefined;
 		assert(this.withCursors.size === 0, 0x774 /* free should remove all cursors */);
 		assert(this.withAnchors.size === 0, 0x775 /* free should remove all anchors */);
 	}
 
 	public get root(): FlexTreeField {
 		assert(this.disposed === false, 0x804 /* use after dispose */);
+		if (this.lazyRootCache !== undefined) {
+			return this.lazyRootCache;
+		}
+
 		const cursor = this.checkout.forest.allocateCursor("root");
 		moveToDetachedField(this.checkout.forest, cursor);
 		const field = makeField(this, this.schema.rootFieldSchema.kind, cursor);
 		cursor.free();
+		this.lazyRootCache = field;
 		return field;
 	}
 
@@ -175,20 +190,3 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 		return this.checkout.forest.events;
 	}
 }
-
-/**
- * A simple API for a Forest to interact with the tree.
- *
- * @param forest - the Forest
- * @param editor - an editor that makes changes to the forest.
- * @param nodeKeyManager - an object which handles node key generation and conversion.
- * @returns {@link FlexTreeContext} which is used to manage the cursors and anchors within the FlexTrees:
- * This is necessary for supporting using this tree across edits to the forest, and not leaking memory.
- */
-export function getTreeContext(
-	schema: SchemaPolicy,
-	checkout: ITreeCheckout,
-	nodeKeyManager: NodeIdentifierManager,
-): Context {
-	return new Context(schema, checkout, nodeKeyManager);
-}

package/src/feature-libraries/flex-tree/index.ts

@@ -28,7 +28,6 @@ export {
 } from "./navigation.js";
 
 export {
-	getTreeContext,
 	type FlexTreeContext,
 	type FlexTreeHydratedContext,
 	Context,

package/src/feature-libraries/flex-tree/lazyField.ts

@@ -278,20 +278,8 @@ export class LazySequence extends LazyField implements FlexTreeSequenceField {
 	}
 }
 
-export class ReadonlyLazyValueField extends LazyField implements FlexTreeRequiredField {
+export class LazyValueField extends LazyField implements FlexTreeRequiredField {
 	public editor: ValueFieldEditBuilder<ExclusiveMapTree> = {
-		set: (newContent) => {
-			assert(false, 0xa0c /* Unexpected set of readonly field */);
-		},
-	};
-
-	public get content(): FlexTreeUnknownUnboxed {
-		return this.atIndex(0);
-	}
-}
-
-export class LazyValueField extends ReadonlyLazyValueField implements FlexTreeRequiredField {
-	public override editor: ValueFieldEditBuilder<ExclusiveMapTree> = {
 		set: (newContent) => {
 			this.valueFieldEditor().set(cursorForMapTreeField([newContent]));
 		},
@@ -303,7 +291,7 @@ export class LazyValueField extends ReadonlyLazyValueField implements FlexTreeRe
 		return fieldEditor;
 	}
 
-	public override get content(): FlexTreeUnknownUnboxed {
+	public get content(): FlexTreeUnknownUnboxed {
 		return this.atIndex(0);
 	}
 }

package/src/feature-libraries/flex-tree/utilities.ts

@@ -11,8 +11,9 @@ import {
 	rootField,
 	type SchemaAndPolicy,
 } from "../../core/index.js";
+import type { FlexTreeContext } from "./context.js";
 
-import { TreeStatus, type FlexTreeEntity } from "./flexTreeTypes.js";
+import { TreeStatus } from "./flexTreeTypes.js";
 /**
  * Checks the detached field and returns the TreeStatus based on whether or not the detached field is a root field.
  * @param detachedField - the detached field you want to check.
@@ -75,15 +76,14 @@ export interface DetachedFieldCache {
 }
 
 /**
- * Utility function to get a {@link SchemaAndPolicy} object from a {@link FlexTreeNode} or {@link FlexTreeField}.
- * @param nodeOrField - {@link FlexTreeNode} or {@link FlexTreeField} to get the schema and policy from.
- * @returns A {@link SchemaAndPolicy} object with the stored schema and policy from the node or field provided.
- * For {@link Unhydrated} nodes this schema may only describe the types allowed subtree for this particular entity.
+ * Utility function to get a {@link SchemaAndPolicy} object from a {@link FlexTreeContext}.
+ * @returns A {@link SchemaAndPolicy} object with the stored schema and policy from the context provided.
+ * For {@link Unhydrated} contexts this schema may only describe the types allowed subtree for this particular entity.
  */
-export function getSchemaAndPolicy(nodeOrField: FlexTreeEntity): SchemaAndPolicy {
+export function getSchemaAndPolicy(context: FlexTreeContext): SchemaAndPolicy {
 	return {
-		schema: nodeOrField.context.schema,
-		policy: nodeOrField.context.schemaPolicy,
+		schema: context.schema,
+		policy: context.schemaPolicy,
 	};
 }
 

package/src/feature-libraries/index.ts

@@ -158,7 +158,6 @@ export {
 	type FlexTreeEntity,
 	type FlexTreeField,
 	type FlexTreeNode,
-	getTreeContext,
 	TreeStatus,
 	Context,
 	type FlexTreeNodeEvents,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.41.0-337492";
+export const pkgVersion = "2.41.0-338186";

package/src/shared-tree/checkoutFlexTreeView.ts

@@ -5,10 +5,9 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 import {
-	type Context,
+	Context,
 	type FlexTreeField,
 	type NodeIdentifierManager,
-	getTreeContext,
 	type FlexTreeHydratedContext,
 	type FullSchemaPolicy,
 } from "../feature-libraries/index.js";
@@ -19,6 +18,10 @@ import type { ITreeCheckout, ITreeCheckoutFork } from "./treeCheckout.js";
 
 /**
  * An editable view of a (version control style) branch of a shared tree.
+ * @remarks
+ * Does not depend on stored schema, and thus can live across schema changes.
+ * @privateRemarks
+ * This has no state beyond the context, so it likely should be replaced with just the context.
  */
 export class CheckoutFlexTreeView<out TCheckout extends ITreeCheckout = ITreeCheckout> {
 	/**
@@ -30,9 +33,11 @@ export class CheckoutFlexTreeView<out TCheckout extends ITreeCheckout = ITreeChe
 	public readonly context: Context;
 
 	/**
-	 * Get a typed view of the tree content using the flex-tree API.
+	 * Get a view of the tree content using the flex-tree API.
 	 */
-	public readonly flexTree: FlexTreeField;
+	public get flexTree(): FlexTreeField {
+		return this.context.root;
+	}
 
 	private disposed = false;
 
@@ -48,9 +53,8 @@ export class CheckoutFlexTreeView<out TCheckout extends ITreeCheckout = ITreeChe
 		public readonly nodeKeyManager: NodeIdentifierManager,
 		private readonly onDispose?: () => void,
 	) {
-		this.context = getTreeContext(schema, this.checkout, nodeKeyManager);
+		this.context = new Context(schema, this.checkout, nodeKeyManager);
 		contextToTreeViewMap.set(this.context, this);
-		this.flexTree = this.context.root;
 	}
 
 	public [disposeSymbol](): void {

package/src/shared-tree/schematizingTreeView.ts

@@ -33,9 +33,6 @@ import {
 	SchemaCompatibilityTester,
 	type InsertableContent,
 	type TreeViewConfiguration,
-	mapTreeFromNodeData,
-	prepareContentForHydration,
-	comparePersistedSchemaInternal,
 	type TreeViewAlpha,
 	type InsertableField,
 	type ReadableField,
@@ -55,6 +52,7 @@ import {
 	SimpleContextSlot,
 	areImplicitFieldSchemaEqual,
 	createUnknownOptionalFieldPolicy,
+	prepareForInsertionContextless,
 } from "../simple-tree/index.js";
 import {
 	type Breakable,
@@ -99,6 +97,9 @@ export class SchematizingSimpleTreeView<
 
 	private readonly viewSchema: SchemaCompatibilityTester;
 
+	/**
+	 * Events to unregister upon disposal.
+	 */
 	private readonly unregisterCallbacks = new Set<() => void>();
 
 	public disposed = false;
@@ -174,17 +175,16 @@ export class SchematizingSimpleTreeView<
 
 		this.runSchemaEdit(() => {
 			const schema = this.viewSchema.viewSchemaAsStored;
-			const mapTree = mapTreeFromNodeData(
+			const mapTree = prepareForInsertionContextless(
 				content as InsertableContent | undefined,
 				this.rootFieldSchema,
-				this.nodeKeyManager,
 				{
 					schema,
 					policy: this.schemaPolicy,
 				},
+				this,
 			);
 
-			prepareContentForHydration(mapTree, this.checkout.forest);
 			initialize(this.checkout, {
 				schema,
 				initialTree: mapTree === undefined ? undefined : cursorForMapTreeNode(mapTree),
@@ -324,15 +324,14 @@ export class SchematizingSimpleTreeView<
 	private update(): void {
 		this.disposeView();
 
-		const compatibility = comparePersistedSchemaInternal(
-			this.checkout.storedSchema,
-			this.viewSchema,
-			canInitialize(this.checkout),
-		);
+		const compatibility = this.viewSchema.checkCompatibility(this.checkout.storedSchema);
 
 		let lastRoot =
 			this.compatibility.canView && this.view !== undefined ? this.root : undefined;
-		this.currentCompatibility = compatibility;
+		this.currentCompatibility = {
+			...compatibility,
+			canInitialize: canInitialize(this.checkout),
+		};
 
 		if (compatibility.canView) {
 			// Trigger "rootChanged" if the root changes in the future.

package/src/shared-tree/treeAlpha.ts

@@ -36,6 +36,7 @@ import {
 	extractPersistedSchema,
 	type TreeBranch,
 	TreeViewConfigurationAlpha,
+	mapTreeFromNodeData,
 } from "../simple-tree/index.js";
 import type { JsonCompatible } from "../util/index.js";
 import { noopValidator, type FluidClientVersion, type ICodecOptions } from "../codec/index.js";
@@ -53,6 +54,7 @@ import {
 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";
 
 /**
  * Extensions to {@link (Tree:interface)} and {@link (TreeBeta:interface)} which are not yet stable.
@@ -80,11 +82,8 @@ 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.
-	 *
-	 * Like with {@link TreeNodeSchemaClass}'s constructor, it's an error to provide an existing node to this API.
-	 * For that case, use {@link (TreeBeta:interface).clone}.
 	 * @privateRemarks
-	 * There should be a way to provide a source for defaulted identifiers, wither via this API or some way to add them to its output later.
+	 * 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
@@ -229,7 +228,24 @@ export const TreeAlpha: TreeAlpha = {
 		return view;
 	},
 
-	create: createFromInsertable,
+	create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(
+		schema: UnsafeUnknownSchema extends TSchema
+			? ImplicitFieldSchema
+			: TSchema & ImplicitFieldSchema,
+		data: InsertableField<TSchema>,
+	): Unhydrated<
+		TSchema extends ImplicitFieldSchema
+			? TreeFieldFromImplicitField<TSchema>
+			: TreeNode | TreeLeafValue | undefined
+	> {
+		const mapTree = mapTreeFromNodeData(data as InsertableField<UnsafeUnknownSchema>, schema);
+		const result = mapTree === undefined ? undefined : createFromMapTree(schema, mapTree);
+		return result as Unhydrated<
+			TSchema extends ImplicitFieldSchema
+				? TreeFieldFromImplicitField<TSchema>
+				: TreeNode | TreeLeafValue | undefined
+		>;
+	},
 
 	importConcise<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(
 		schema: UnsafeUnknownSchema extends TSchema

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

@@ -5,7 +5,11 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 
-import type { ITreeCursorSynchronous, SchemaAndPolicy } from "../../core/index.js";
+import type {
+	ExclusiveMapTree,
+	ITreeCursorSynchronous,
+	SchemaAndPolicy,
+} from "../../core/index.js";
 import type {
 	ImplicitFieldSchema,
 	TreeFieldFromImplicitField,
@@ -24,12 +28,10 @@ import {
 import {
 	cursorForMapTreeNode,
 	defaultSchemaPolicy,
-	FieldKinds,
 	mapTreeFromCursor,
 	type NodeIdentifierManager,
 } from "../../feature-libraries/index.js";
 import { isFieldInSchema } from "../../feature-libraries/index.js";
-import { toStoredSchema } from "../toStoredSchema.js";
 import { inSchemaOrThrow, mapTreeFromNodeData } from "../toMapTree.js";
 import { getUnhydratedContext } from "../createContext.js";
 import { createUnknownOptionalFieldPolicy } from "../objectNode.js";
@@ -88,24 +90,12 @@ export function cursorFromInsertable<
 ):
 	| ITreeCursorSynchronous
 	| (TSchema extends FieldSchema<FieldKind.Optional> ? undefined : never) {
-	const storedSchema = toStoredSchema(schema);
-	const schemaValidationPolicy: SchemaAndPolicy = {
-		policy: defaultSchemaPolicy,
-		// TODO: optimize: This isn't the most efficient operation since its not cached, and has to convert all the schema.
-		schema: storedSchema,
-	};
-
 	const mapTree = mapTreeFromNodeData(
 		data as InsertableField<UnsafeUnknownSchema>,
 		schema,
 		context,
-		schemaValidationPolicy,
 	);
 	if (mapTree === undefined) {
-		assert(
-			storedSchema.rootFieldSchema.kind === FieldKinds.optional.identifier,
-			0xa10 /* missing non-optional field */,
-		);
 		return undefined as TSchema extends FieldSchema<FieldKind.Optional> ? undefined : never;
 	}
 	return cursorForMapTreeNode(mapTree);
@@ -144,6 +134,16 @@ 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);
+}
+
+/**
+ * Creates an unhydrated simple-tree field from an ExclusiveMapTree.
+ */
+export function createFromMapTree<const TSchema extends ImplicitFieldSchema>(
+	schema: TSchema,
+	mapTree: ExclusiveMapTree,
+): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
 	const mapTreeNode = UnhydratedFlexTreeNode.getOrCreate(
 		getUnhydratedContext(schema),
 		mapTree,

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

@@ -45,7 +45,12 @@ export {
 	singletonSchema,
 } from "./schemaCreationUtilities.js";
 export { treeNodeApi, type TreeNodeApi, tryGetSchema } from "./treeNodeApi.js";
-export { createFromInsertable, cursorFromInsertable, createFromCursor } from "./create.js";
+export {
+	createFromInsertable,
+	cursorFromInsertable,
+	createFromCursor,
+	createFromMapTree,
+} from "./create.js";
 export {
 	type JsonSchemaId,
 	type JsonSchemaType,
@@ -107,7 +112,6 @@ export {
 
 export {
 	extractPersistedSchema,
-	comparePersistedSchemaInternal,
 	comparePersistedSchema,
 } from "./storedSchema.js";
 

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

@@ -4,7 +4,6 @@
  */
 
 import type { FluidClientVersion, ICodecOptions } from "../../codec/index.js";
-import type { TreeStoredSchema } from "../../core/index.js";
 import {
 	defaultSchemaPolicy,
 	encodeTreeSchema,
@@ -96,8 +95,7 @@ export function comparePersistedSchema(
 	persisted: JsonCompatible,
 	view: ImplicitFieldSchema,
 	options: ICodecOptions,
-	canInitialize: boolean,
-): SchemaCompatibilityStatus {
+): Omit<SchemaCompatibilityStatus, "canInitialize"> {
 	// Any version can be passed down to makeSchemaCodec here.
 	// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.
 	const schemaCodec = makeSchemaCodec(options, SchemaCodecVersion.v1);
@@ -107,20 +105,5 @@ export function comparePersistedSchema(
 		{},
 		normalizeFieldSchema(view),
 	);
-	return comparePersistedSchemaInternal(stored, viewSchema, canInitialize);
-}
-
-/**
- * Compute compatibility for viewing a document with `stored` schema using `viewSchema`.
- * `canInitialize` is passed through to the return value unchanged and otherwise unused.
- */
-export function comparePersistedSchemaInternal(
-	stored: TreeStoredSchema,
-	viewSchema: SchemaCompatibilityTester,
-	canInitialize: boolean,
-): SchemaCompatibilityStatus {
-	return {
-		...viewSchema.checkCompatibility(stored),
-		canInitialize,
-	};
+	return viewSchema.checkCompatibility(stored);
 }

package/src/simple-tree/arrayNode.ts

@@ -10,10 +10,8 @@ import { EmptyKey, type ExclusiveMapTree } from "../core/index.js";
 import {
 	type FlexTreeNode,
 	type FlexTreeSequenceField,
-	getSchemaAndPolicy,
 	isFlexTreeNode,
 } from "../feature-libraries/index.js";
-import { prepareContentForHydration } from "./proxies.js";
 import {
 	normalizeAllowedTypes,
 	unannotateImplicitAllowedTypes,
@@ -41,6 +39,7 @@ import {
 	type TreeNodeSchemaClass,
 } from "./core/index.js";
 import { type InsertableContent, mapTreeFromNodeData } from "./toMapTree.js";
+import { prepareArrayForInsertion } from "./prepareForInsertion.js";
 import {
 	getKernel,
 	UnhydratedFlexTreeNode,
@@ -860,24 +859,14 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			| IterableTreeArrayContent<InsertableContent>
 		)[];
 
-		const mapTrees = content
-			.flatMap((c): InsertableContent[] =>
-				c instanceof IterableTreeArrayContent ? Array.from(c) : [c],
-			)
-			.map((c) =>
-				mapTreeFromNodeData(
-					c,
-					this.simpleSchema,
-					sequenceField.context.isHydrated()
-						? sequenceField.context.nodeKeyManager
-						: undefined,
-					getSchemaAndPolicy(sequenceField),
-				),
-			);
-
-		if (sequenceField.context.isHydrated()) {
-			prepareContentForHydration(mapTrees, sequenceField.context.checkout.forest);
-		}
+		const contentArray = content.flatMap((c): InsertableContent[] =>
+			c instanceof IterableTreeArrayContent ? Array.from(c) : [c],
+		);
+		const mapTrees = prepareArrayForInsertion(
+			contentArray,
+			this.simpleSchema,
+			sequenceField.context,
+		);
 
 		return mapTrees;
 	}

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

@@ -69,7 +69,7 @@ interface LocationInField {
  * An unhydrated implementation of {@link FlexTreeNode} which wraps a {@link MapTree}.
  * @remarks
  * MapTreeNodes are unconditionally cached -
- * when retrieved via {@link getOrCreateNode}, the same {@link MapTree} object will always produce the same `UnhydratedFlexTreeNode` object.
+ * when retrieved via {@link getOrCreateNodeFromInnerNode}, the same {@link MapTree} object will always produce the same `UnhydratedFlexTreeNode` object.
  *
  * Create a `UnhydratedFlexTreeNode` by calling {@link getOrCreate}.
  */
@@ -112,9 +112,9 @@ export class UnhydratedFlexTreeNode implements FlexTreeNode {
 	 * Create a new UnhydratedFlexTreeNode.
 	 * @param location - the parentage of this node, if it is being created underneath an existing node and field, or undefined if not
 	 * @remarks This class (and its subclasses) should not be directly constructed outside of this module.
-	 * Instead, use {@link getOrCreateNode} to create a UnhydratedFlexTreeNode from a {@link MapTree}.
+	 * Instead, use {@link getOrCreateNodeFromInnerNode} to create a UnhydratedFlexTreeNode from a {@link MapTree}.
 	 * A `UnhydratedFlexTreeNode` may never be constructed more than once for the same {@link MapTree} object.
-	 * Instead, it should always be acquired via {@link getOrCreateNode}.
+	 * Instead, it should always be acquired via {@link getOrCreateNodeFromInnerNode}.
 	 */
 	public constructor(
 		public readonly simpleContext: Context,
@@ -548,7 +548,7 @@ function getFieldKeyCache(
 
 /**
  * If there exists a {@link UnhydratedFlexTreeNode} for the given {@link MapTree}, returns it, otherwise returns `undefined`.
- * @remarks {@link UnhydratedFlexTreeNode | UnhydratedFlexTreeNodes} are created via {@link getOrCreateNode}.
+ * @remarks {@link UnhydratedFlexTreeNode | UnhydratedFlexTreeNodes} are created via {@link getOrCreateNodeFromInnerNode}.
  */
 export function tryUnhydratedFlexTreeNode(
 	mapTree: MapTree,