@fluidframework/tree 2.31.1 → 2.33.0-333010

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

@@ -10,14 +10,15 @@ import {
 	type AllowedTypes,
 	type FieldSchemaAlpha,
 	FieldKind,
+	type FieldProps,
 } from "../schemaTypes.js";
-import { SchemaFactory } from "./schemaFactory.js";
 import type {
 	SimpleFieldSchema,
 	SimpleNodeSchema,
 	SimpleTreeSchema,
 } from "../simpleSchema.js";
 import { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
+import type { TreeSchema } from "./tree.js";
 
 const factory = new SchemaFactoryAlpha(undefined);
 
@@ -30,31 +31,53 @@ const factory = new SchemaFactoryAlpha(undefined);
  * will produce a poor TypeScript typing experience which is subject to change.
  *
  * Editing through a view produced using this schema can easily violate invariants other users of the document might expect and must be done with great care.
+ *
+ * This API bakes in some arbitrary policy choices for how to handle data that is not included in the SimpleTreeSchema API, for example the value of `allowUnknownOptionalFields`.
+ * If any particular choice is required for such cases, this API should not be used.
  * @alpha
  */
-export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): FieldSchemaAlpha {
+export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSchema {
 	const context: Context = new Map(
-		[...simple.definitions].map(([id, schema]): [string, () => TreeNodeSchema] => [
-			id,
-			// This relies on the caching in evaluateLazySchema so that it only runs once.
-			() => generateNode(id, schema, context),
-		]),
+		[...simple.definitions].map(
+			([id, schema]): [string, () => TreeNodeSchema & SimpleNodeSchema] => [
+				id,
+				// This relies on the caching in evaluateLazySchema so that it only runs once.
+				() => generateNode(id, schema, context),
+			],
+		),
 	);
-	return generateFieldSchema(simple, context);
+	const root = generateFieldSchema(simple.root, context, undefined);
+	const definitions = new Map<string, TreeNodeSchema & SimpleNodeSchema>();
+	for (const [id, lazy] of context) {
+		definitions.set(id, lazy());
+	}
+	return {
+		root,
+		definitions,
+	};
 }
 
-type Context = ReadonlyMap<string, () => TreeNodeSchema>;
+type Context = ReadonlyMap<string, () => TreeNodeSchema & SimpleNodeSchema>;
 
-function generateFieldSchema(simple: SimpleFieldSchema, context: Context): FieldSchemaAlpha {
+function generateFieldSchema(
+	simple: SimpleFieldSchema,
+	context: Context,
+	storedKey: string | undefined,
+): FieldSchemaAlpha {
 	const allowed = generateAllowedTypes(simple.allowedTypesIdentifiers, context);
+	const props: Omit<FieldProps, "defaultProvider"> = {
+		metadata: simple.metadata,
+		key: storedKey,
+	};
+
 	// Using createFieldSchema could work, but would require setting up the default providers.
 	switch (simple.kind) {
 		case FieldKind.Identifier:
-			return SchemaFactoryAlpha.identifier({ metadata: simple.metadata });
+			return SchemaFactoryAlpha.identifier(props);
 		case FieldKind.Optional:
-			return SchemaFactoryAlpha.optional(allowed, { metadata: simple.metadata });
+			return SchemaFactoryAlpha.optional(allowed, props);
 		case FieldKind.Required:
-			return SchemaFactoryAlpha.required(allowed, { metadata: simple.metadata });
+			return SchemaFactoryAlpha.required(allowed, props);
 		default:
 			return unreachableCase(simple.kind);
 	}
@@ -64,13 +87,19 @@ function generateAllowedTypes(allowed: ReadonlySet<string>, context: Context): A
 	return [...allowed].map((id) => context.get(id) ?? fail(0xb5a /* Missing schema */));
 }
 
-function generateNode(id: string, schema: SimpleNodeSchema, context: Context): TreeNodeSchema {
+function generateNode(
+	id: string,
+	schema: SimpleNodeSchema,
+	context: Context,
+): TreeNodeSchema & SimpleNodeSchema {
 	switch (schema.kind) {
 		case NodeKind.Object: {
 			const fields: Record<string, FieldSchema> = {};
 			for (const [key, field] of schema.fields) {
-				fields[key] = generateFieldSchema(field, context);
+				fields[key] = generateFieldSchema(field, context, field.storedKey);
 			}
+			// Here allowUnknownOptionalFields is implicitly defaulting. This is a subjective policy choice:
+			// users of this code are expected to handle what ever choice this code makes for cases like this.
 			return factory.object(id, fields, { metadata: schema.metadata });
 		}
 		case NodeKind.Array:
@@ -87,7 +116,7 @@ function generateNode(id: string, schema: SimpleNodeSchema, context: Context): T
 			);
 		case NodeKind.Leaf:
 			return (
-				SchemaFactory.leaves.find((leaf) => leaf.identifier === id) ??
+				SchemaFactoryAlpha.leaves.find((leaf) => leaf.identifier === id) ??
 				fail(0xb5b /* Missing schema */)
 			);
 		default:

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

@@ -6,7 +6,7 @@
 import { unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { ValueSchema } from "../../core/index.js";
-import { copyProperty, getOrCreate, hasSingle, type Mutable } from "../../util/index.js";
+import { copyProperty, hasSingle, type Mutable } from "../../util/index.js";
 import type {
 	JsonArrayNodeSchema,
 	JsonFieldSchema,
@@ -24,24 +24,39 @@ import type {
 	SimpleArrayNodeSchema,
 	SimpleLeafNodeSchema,
 	SimpleMapNodeSchema,
-	SimpleNodeSchema,
-	SimpleObjectNodeSchema,
-	SimpleTreeSchema,
 } from "../simpleSchema.js";
-import { NodeKind } from "../core/index.js";
+import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+import type { TreeSchema } from "./tree.js";
+import type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
+import { ObjectNodeSchema } from "../objectNodeTypes.js";
+import { ArrayNodeSchema } from "../arrayNodeTypes.js";
+import { MapNodeSchema } from "../mapNodeTypes.js";
+import { LeafNodeSchema } from "../leafNodeSchema.js";
 
 /**
  * Generates a JSON Schema representation from a simple tree schema.
+ * @remarks
+ * This expects the data to be in the {@link ConciseTree} format.
+ *
+ * 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: SimpleTreeSchema): JsonTreeSchema {
-	const definitions = convertDefinitions(schema.definitions);
+export function toJsonSchema(
+	schema: TreeSchema,
+	options: Required<TreeSchemaEncodingOptions>,
+): JsonTreeSchema {
+	const definitions = convertDefinitions(schema.definitions, options);
 
 	const allowedTypes: JsonSchemaRef[] = [];
-	for (const allowedType of schema.allowedTypesIdentifiers) {
+	for (const allowedType of schema.root.allowedTypesIdentifiers) {
 		allowedTypes.push(createSchemaRef(allowedType));
 	}
 
+	// 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.
 	return hasSingle(allowedTypes)
 		? {
 				...allowedTypes[0],
@@ -54,40 +69,35 @@ export function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {
 }
 
 function convertDefinitions(
-	definitions: ReadonlyMap<string, SimpleNodeSchema>,
+	definitions: ReadonlyMap<string, TreeNodeSchema>,
+	options: Required<TreeSchemaEncodingOptions>,
 ): Record<string, JsonNodeSchema> {
 	const result: Record<string, JsonNodeSchema> = {};
 	for (const [key, value] of definitions) {
-		result[key] = convertNodeSchema(value);
+		result[key] = convertNodeSchema(value, options);
 	}
 	return result;
 }
 
-/**
- * Private symbol under which the results of {@link convertNodeSchema} are cached on an input {@link SimpleNodeSchema}.
- */
-const nodeJsonSchemaCache = new WeakMap<SimpleNodeSchema, JsonNodeSchema>();
-
 /**
  * Converts an input {@link SimpleNodeSchema} to a {@link JsonNodeSchema}.
  *
  * @remarks Caches the result on the input schema for future calls.
  */
-function convertNodeSchema(schema: SimpleNodeSchema): JsonNodeSchema {
-	return getOrCreate(nodeJsonSchemaCache, schema, () => {
-		switch (schema.kind) {
-			case NodeKind.Array:
-				return convertArrayNodeSchema(schema);
-			case NodeKind.Leaf:
-				return convertLeafNodeSchema(schema);
-			case NodeKind.Map:
-				return convertMapNodeSchema(schema);
-			case NodeKind.Object:
-				return convertObjectNodeSchema(schema);
-			default:
-				throw new TypeError(`Unknown node schema kind: ${(schema as SimpleNodeSchema).kind}`);
-		}
-	});
+function convertNodeSchema(
+	schema: TreeNodeSchema,
+	options: Required<TreeSchemaEncodingOptions>,
+): JsonNodeSchema {
+	if (schema instanceof ArrayNodeSchema) {
+		return convertArrayNodeSchema(schema);
+	} else if (schema instanceof MapNodeSchema) {
+		return convertMapNodeSchema(schema);
+	} else if (schema instanceof ObjectNodeSchema) {
+		return convertObjectNodeSchema(schema, options);
+	} else if (schema instanceof LeafNodeSchema) {
+		return convertLeafNodeSchema(schema);
+	}
+	throw new TypeError(`Unknown node schema kind: ${schema.kind}`);
 }
 
 function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSchema {
@@ -138,10 +148,14 @@ function convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema
 	};
 }
 
-export function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNodeSchema {
+export function convertObjectNodeSchema(
+	schema: ObjectNodeSchema,
+	options: Required<TreeSchemaEncodingOptions>,
+): JsonObjectNodeSchema {
 	const properties: Record<string, JsonFieldSchema> = {};
 	const required: string[] = [];
-	for (const [key, fieldSchema] of schema.fields) {
+	for (const [propertyKey, fieldSchema] of schema.fields) {
+		const key = options.useStoredKeys ? fieldSchema.storedKey : propertyKey;
 		const allowedTypes: JsonSchemaRef[] = [];
 		for (const allowedType of fieldSchema.allowedTypesIdentifiers) {
 			allowedTypes.push(createSchemaRef(allowedType));
@@ -156,8 +170,13 @@ export function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObj
 		copyProperty(fieldSchema.metadata, "description", output);
 		properties[key] = output;
 
-		if (fieldSchema.kind === FieldKind.Required) {
-			required.push(key);
+		if (fieldSchema.kind !== FieldKind.Optional) {
+			if (
+				options.requireFieldsWithDefaults ||
+				fieldSchema.props?.defaultProvider === undefined
+			) {
+				required.push(key);
+			}
 		}
 	}
 

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

@@ -20,6 +20,7 @@ import type {
 } from "../../shared-tree/index.js";
 
 import {
+	type FieldSchemaAlpha,
 	type ImplicitFieldSchema,
 	type InsertableField,
 	type InsertableTreeFieldFromImplicitField,
@@ -29,6 +30,7 @@ import {
 	type UnsafeUnknownSchema,
 	FieldKind,
 	markSchemaMostDerived,
+	normalizeFieldSchema,
 } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import { toStoredSchema } from "../toStoredSchema.js";
@@ -38,7 +40,7 @@ import { getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
 import type { VerboseTree } from "./verboseTree.js";
-import type { SimpleTreeSchema } from "../simpleSchema.js";
+import type { SimpleNodeSchema, SimpleTreeSchema } from "../simpleSchema.js";
 import type {
 	RunTransactionParams,
 	TransactionCallbackStatus,
@@ -106,9 +108,7 @@ export interface ITree extends ViewableTree, IFluidLoadable {}
 
 /**
  * {@link ITree} extended with some alpha APIs.
- * @privateRemarks
- * TODO: Promote this to alpha.
- * @internal
+ * @sealed @alpha
  */
 export interface ITreeAlpha extends ITree {
 	/**
@@ -309,6 +309,53 @@ export class TreeViewConfiguration<
 	}
 }
 
+/**
+ * {@link TreeViewConfiguration} extended with some alpha APIs.
+ * @sealed @alpha
+ */
+export class TreeViewConfigurationAlpha<
+		const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
+	>
+	extends TreeViewConfiguration<TSchema>
+	implements TreeSchema
+{
+	/**
+	 * {@inheritDoc TreeSchema.root}
+	 */
+	public readonly root: FieldSchemaAlpha;
+	/**
+	 * {@inheritDoc TreeSchema.definitions}
+	 */
+	public readonly definitions: ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
+
+	public constructor(props: ITreeViewConfiguration<TSchema>) {
+		super(props);
+		this.root = normalizeFieldSchema(props.schema);
+		const definitions = new Map<string, SimpleNodeSchema & TreeNodeSchema>();
+		walkFieldSchema(props.schema, {
+			node: (schema) =>
+				definitions.set(schema.identifier, schema as SimpleNodeSchema & TreeNodeSchema),
+		});
+		this.definitions = definitions;
+	}
+}
+
+/**
+ * {@link TreeViewConfigurationAlpha}
+ * @sealed @alpha
+ */
+export interface TreeSchema extends SimpleTreeSchema {
+	/**
+	 * {@inheritDoc SimpleTreeSchema.root}
+	 */
+	readonly root: FieldSchemaAlpha;
+
+	/**
+	 * {@inheritDoc SimpleTreeSchema.definitions}
+	 */
+	readonly definitions: ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
+}
+
 /**
  * Pretty print a set of types for use in error messages.
  */

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

@@ -41,8 +41,9 @@ import {
 	customFromCursor,
 	replaceHandles,
 	type CustomTreeNode,
-	type EncodeOptions,
 	type HandleConverter,
+	type SchemalessParseOptions,
+	type TreeEncodingOptions,
 } from "./customTree.js";
 import { getUnhydratedContext } from "../createContext.js";
 
@@ -110,40 +111,14 @@ export interface VerboseTreeNode<THandle = IFluidHandle> {
 		  };
 }
 
-/**
- * Options for how to interpret a `VerboseTree` when schema information is available.
- * @alpha
- */
-export interface ParseOptions {
-	/**
-	 * If true, interpret the input keys of object nodes as stored keys.
-	 * If false, interpret them as property keys.
-	 * @defaultValue false.
-	 */
-	readonly useStoredKeys?: boolean;
-}
-
-/**
- * Options for how to interpret a `VerboseTree` without relying on schema.
- */
-export interface SchemalessParseOptions {
-	/**
-	 * Converts stored keys into whatever key the tree is using in its encoding.
-	 */
-	keyConverter?: {
-		parse(type: string, inputKey: string): FieldKey;
-		encode(type: string, key: FieldKey): string;
-	};
-}
-
 /**
  * Use info from `schema` to convert `options` to {@link SchemalessParseOptions}.
  */
 export function applySchemaToParserOptions(
 	schema: ImplicitFieldSchema,
-	options: ParseOptions,
+	options: TreeEncodingOptions,
 ): SchemalessParseOptions {
-	const config: Required<ParseOptions> = {
+	const config: Required<TreeEncodingOptions> = {
 		useStoredKeys: false,
 		...options,
 	};
@@ -305,9 +280,9 @@ function verboseTreeAdapter(options: SchemalessParseOptions): CursorAdapter<Verb
 export function verboseFromCursor(
 	reader: ITreeCursor,
 	rootSchema: ImplicitAllowedTypes,
-	options: EncodeOptions,
+	options: TreeEncodingOptions,
 ): VerboseTree {
-	const config: Required<EncodeOptions> = {
+	const config: Required<TreeEncodingOptions> = {
 		useStoredKeys: false,
 		...options,
 	};
@@ -319,7 +294,7 @@ export function verboseFromCursor(
 
 function verboseFromCursorInner(
 	reader: ITreeCursor,
-	options: Required<EncodeOptions>,
+	options: Required<TreeEncodingOptions>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): VerboseTree {
 	const fields = customFromCursor(reader, options, schema, verboseFromCursorInner);

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

@@ -7,6 +7,7 @@ import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "../schemaTypes.js";
 import type {
 	SimpleArrayNodeSchema,
+	SimpleFieldSchema,
 	SimpleLeafNodeSchema,
 	SimpleMapNodeSchema,
 	SimpleNodeSchema,
@@ -59,10 +60,14 @@ export function toSimpleTreeSchema(
 	});
 
 	return {
-		kind: normalizedSchema.kind,
-		allowedTypesIdentifiers: normalizedSchema.allowedTypesIdentifiers,
+		root: copySchemaObjects
+			? ({
+					allowedTypesIdentifiers: normalizedSchema.allowedTypesIdentifiers,
+					kind: normalizedSchema.kind,
+					metadata: normalizedSchema.metadata,
+				} satisfies SimpleFieldSchema)
+			: normalizedSchema,
 		definitions,
-		metadata: normalizedSchema.metadata,
 	};
 }
 

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

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { assert, Lazy, fail } from "@fluidframework/core-utils/internal";
+import { assert, Lazy, fail, debugAssert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { Listenable, Off } from "@fluidframework/core-interfaces";
 import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
@@ -19,7 +20,6 @@ import {
 	assertFlexTreeEntityNotFreed,
 	ContextSlot,
 	flexTreeSlot,
-	isFreedSymbol,
 	LazyEntity,
 	TreeStatus,
 	treeStatusFromAnchorCache,
@@ -73,7 +73,7 @@ export function tryGetTreeNodeSchema(value: unknown): undefined | TreeNodeSchema
 /** The {@link HydrationState} of a {@link TreeNodeKernel} before the kernel is hydrated */
 interface UnhydratedState {
 	off: Off;
-	innerNode: UnhydratedFlexTreeNode;
+	readonly innerNode: UnhydratedFlexTreeNode;
 }
 
 /** The {@link HydrationState} of a {@link TreeNodeKernel} after the kernel is hydrated */
@@ -81,9 +81,9 @@ interface HydratedState {
 	/** The flex node for this kernel (lazy - undefined if it has not yet been demanded) */
 	innerNode?: FlexTreeNode;
 	/** The {@link AnchorNode} that this node is associated with. */
-	anchorNode: AnchorNode;
+	readonly anchorNode: AnchorNode;
 	/** All {@link Off | event deregistration functions} that should be run when the kernel is disposed. */
-	offAnchorNode: Set<Off>;
+	readonly offAnchorNode: Set<Off>;
 }
 
 /** State within a {@link TreeNodeKernel} that is related to the hydration process */
@@ -155,15 +155,20 @@ export class TreeNodeKernel {
 						changedFields,
 					});
 
-					let n: UnhydratedFlexTreeNode | undefined = innerNode;
-					while (n !== undefined) {
-						const treeNode = unhydratedFlexTreeNodeToTreeNodeInternal.get(n);
+					let unhydratedNode: UnhydratedFlexTreeNode | undefined = innerNode;
+					while (unhydratedNode !== undefined) {
+						const treeNode = unhydratedFlexTreeNodeToTreeNodeInternal.get(unhydratedNode);
 						if (treeNode !== undefined) {
 							const kernel = getKernel(treeNode);
 							kernel.#unhydratedEvents.value.emit("subtreeChangedAfterBatch");
 						}
-						// This cast is safe because the parent (if it exists) of an unhydrated flex node is always another unhydrated flex node.
-						n = n.parentField.parent.parent as UnhydratedFlexTreeNode | undefined;
+						const parentNode: FlexTreeNode | undefined =
+							unhydratedNode.parentField.parent.parent;
+						assert(
+							parentNode === undefined || parentNode instanceof UnhydratedFlexTreeNode,
+							0xb76 /* Unhydrated node's parent should be an unhydrated node */,
+						);
+						unhydratedNode = parentNode;
 					}
 				}),
 			};
@@ -243,7 +248,7 @@ export class TreeNodeKernel {
 		const flex = this.#hydrationState.anchorNode.slots.get(flexTreeSlot);
 		if (flex !== undefined) {
 			assert(flex instanceof LazyEntity, 0x9b4 /* Unexpected flex node implementation */);
-			if (flex[isFreedSymbol]()) {
+			if (flex.isFreed()) {
 				return TreeStatus.Deleted;
 			}
 		}
@@ -283,35 +288,46 @@ export class TreeNodeKernel {
 	 *
 	 * For hydrated nodes it returns a FlexTreeNode backed by the forest.
 	 * Note that for "marinated" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.
+	 *
+	 * If `allowDeleted` is false, this will throw a UsageError if the node is deleted.
 	 */
-	public getOrCreateInnerNode(allowFreed = false): InnerNode {
+	public getOrCreateInnerNode(allowDeleted = false): InnerNode {
 		if (!isHydrated(this.#hydrationState)) {
+			debugAssert(
+				() =>
+					this.#hydrationState.innerNode?.context.isDisposed() === false ||
+					"Unhydrated node should never be disposed",
+			);
 			return this.#hydrationState.innerNode; // Unhydrated case
 		}
 
-		if (this.#hydrationState.innerNode !== undefined) {
-			return this.#hydrationState.innerNode; // Cooked case
+		if (this.#hydrationState.innerNode === undefined) {
+			// Marinated case -> cooked
+			const anchorNode = this.#hydrationState.anchorNode;
+			// The proxy is bound to an anchor node, but it may or may not have an actual flex node yet
+			const flexNode = anchorNode.slots.get(flexTreeSlot);
+			if (flexNode !== undefined) {
+				// If the flex node already exists, use it...
+				this.#hydrationState.innerNode = flexNode;
+			} else {
+				// ...otherwise, the flex node must be created
+				const context =
+					anchorNode.anchorSet.slots.get(ContextSlot) ?? fail(0xb41 /* missing context */);
+				const cursor = context.checkout.forest.allocateCursor("getFlexNode");
+				context.checkout.forest.moveCursorToPath(anchorNode, cursor);
+				this.#hydrationState.innerNode = makeTree(context, cursor);
+				cursor.free();
+				// Calling this is a performance improvement, however, do this only after demand to avoid momentarily having no anchors to anchorNode
+				anchorForgetters?.get(this.node)?.();
+				if (!allowDeleted) {
+					assertFlexTreeEntityNotFreed(this.#hydrationState.innerNode);
+				}
+			}
 		}
 
-		// Marinated case -> cooked
-		const anchorNode = this.#hydrationState.anchorNode;
-		// The proxy is bound to an anchor node, but it may or may not have an actual flex node yet
-		const flexNode = anchorNode.slots.get(flexTreeSlot);
-		if (flexNode !== undefined) {
-			// If the flex node already exists, use it...
-			this.#hydrationState.innerNode = flexNode;
-		} else {
-			// ...otherwise, the flex node must be created
-			const context =
-				anchorNode.anchorSet.slots.get(ContextSlot) ?? fail(0xb41 /* missing context */);
-			const cursor = context.checkout.forest.allocateCursor("getFlexNode");
-			context.checkout.forest.moveCursorToPath(anchorNode, cursor);
-			this.#hydrationState.innerNode = makeTree(context, cursor);
-			cursor.free();
-			// Calling this is a performance improvement, however, do this only after demand to avoid momentarily having no anchors to anchorNode
-			anchorForgetters?.get(this.node)?.();
-			if (!allowFreed) {
-				assertFlexTreeEntityNotFreed(this.#hydrationState.innerNode);
+		if (!allowDeleted) {
+			if (this.#hydrationState.innerNode.context.isDisposed()) {
+				throw new UsageError("Cannot access a Deleted node.");
 			}
 		}
 
@@ -413,11 +429,15 @@ export const unhydratedFlexTreeNodeToTreeNode =
  */
 export const proxySlot = anchorSlot<TreeNode>();
 
+/**
+ * Dispose a TreeNode (if any) for an existing anchor without disposing the anchor.
+ */
 export function tryDisposeTreeNode(anchorNode: AnchorNode): void {
 	const treeNode = anchorNode.slots.get(proxySlot);
 	if (treeNode !== undefined) {
 		const kernel = getKernel(treeNode);
 		kernel.dispose();
+		anchorNode.slots.delete(proxySlot);
 	}
 }
 
@@ -450,10 +470,12 @@ export function getSimpleContextFromInnerNode(innerNode: InnerNode): Context {
  *
  * For hydrated nodes it returns a FlexTreeNode backed by the forest.
  * Note that for "marinated" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.
+ *
+ * If `allowDeleted` is false, this will throw a UsageError if the node is deleted.
  */
-export function getOrCreateInnerNode(treeNode: TreeNode, allowFreed = false): InnerNode {
+export function getOrCreateInnerNode(treeNode: TreeNode, allowDeleted = false): InnerNode {
 	const kernel = getKernel(treeNode);
-	return kernel.getOrCreateInnerNode(allowFreed);
+	return kernel.getOrCreateInnerNode(allowDeleted);
 }
 
 /**

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

@@ -73,7 +73,7 @@ interface LocationInField {
  *
  * Create a `UnhydratedFlexTreeNode` by calling {@link getOrCreate}.
  */
-export class UnhydratedFlexTreeNode implements UnhydratedFlexTreeNode {
+export class UnhydratedFlexTreeNode implements FlexTreeNode {
 	public get schema(): TreeNodeSchemaIdentifier {
 		return this.mapTree.type;
 	}
@@ -150,11 +150,24 @@ export class UnhydratedFlexTreeNode implements UnhydratedFlexTreeNode {
 	public adoptBy(parent: UnhydratedFlexTreeField, index: number): void;
 	public adoptBy(parent: UnhydratedFlexTreeField | undefined, index?: number): void {
 		if (parent !== undefined) {
-			assert(
-				this.location === unparentedLocation,
-				0x98c /* Node may not be adopted if it already has a parent */,
-			);
 			assert(index !== undefined, 0xa08 /* Expected index */);
+			if (this.location !== unparentedLocation) {
+				throw new UsageError("A node may not be inserted if it's already in a tree");
+			}
+			let unhydratedNode: UnhydratedFlexTreeNode | undefined = parent.parent;
+			while (unhydratedNode !== undefined) {
+				if (unhydratedNode === this) {
+					throw new UsageError(
+						"A node may not be inserted into a location that is under itself",
+					);
+				}
+				const parentNode: FlexTreeNode | undefined = unhydratedNode.parentField.parent.parent;
+				assert(
+					parentNode === undefined || parentNode instanceof UnhydratedFlexTreeNode,
+					0xb77 /* Unhydrated node's parent should be an unhydrated node */,
+				);
+				unhydratedNode = parentNode;
+			}
 			this.location = { parent, index };
 		} else {
 			assert(
@@ -264,6 +277,10 @@ export class UnhydratedContext implements FlexTreeContext {
 		public readonly schema: TreeStoredSchema,
 	) {}
 
+	public isDisposed(): boolean {
+		return false;
+	}
+
 	public isHydrated(): this is FlexTreeHydratedContext {
 		return false;
 	}