@fluidframework/tree 2.10.0-306579 → 2.10.0-307399

package/src/feature-libraries/modular-schema/discrepancies.ts

@@ -6,7 +6,6 @@
 import { assert } from "@fluidframework/core-utils/internal";
 
 import {
-	type FieldKey,
 	type FieldKindIdentifier,
 	LeafNodeStoredSchema,
 	MapNodeStoredSchema,
@@ -14,6 +13,7 @@ import {
 	storedEmptyFieldSchema,
 	type TreeFieldStoredSchema,
 	type TreeNodeSchemaIdentifier,
+	type TreeNodeStoredSchema,
 	type TreeStoredSchema,
 	type TreeTypeSet,
 	type ValueSchema,
@@ -27,45 +27,45 @@ import { brand } from "../../util/index.js";
 /**
  * @remarks
  *
- * 1. FieldIncompatibility
+ * 1. FieldDiscrepancy
  *
- * `FieldIncompatibility` represents the differences between two `TreeFieldStoredSchema` objects. It consists of
+ * `FieldDiscrepancy` represents the differences between two `TreeFieldStoredSchema` objects. It consists of
  * three types of incompatibilities:
  *
- * - FieldKindIncompatibility: Indicates the differences in `FieldKindIdentifier` between two `TreeFieldStoredSchema`
+ * - FieldKindDiscrepancy: Indicates the differences in `FieldKindIdentifier` between two `TreeFieldStoredSchema`
  * objects (e.g., optional, required, sequence, etc.).
- * - AllowedTypesIncompatibility: Indicates the differences in the allowed child types between the two schemas.
- * - ValueSchemaIncompatibility: Specifically indicates the differences in the `ValueSchema` of two
+ * - AllowedTypesDiscrepancy: Indicates the differences in the allowed child types between the two schemas.
+ * - ValueSchemaDiscrepancy: Specifically indicates the differences in the `ValueSchema` of two
  * `LeafNodeStoredSchema` objects.
  *
- * 2. NodeIncompatibility
+ * 2. NodeDiscrepancy
  *
- * `NodeIncompatibility` represents the differences between two `TreeNodeStoredSchema` objects and includes:
+ * `NodeDiscrepancy` represents the differences between two `TreeNodeStoredSchema` objects and includes:
  *
- * - NodeKindIncompatibility: Indicates the differences in the types of `TreeNodeStoredSchema` (currently supports
+ * - NodeKindDiscrepancy: Indicates the differences in the types of `TreeNodeStoredSchema` (currently supports
  * `ObjectNodeStoredSchema`, `MapNodeStoredSchema`, and `LeafNodeStoredSchema`).
- * - NodeFieldsIncompatibility: Indicates the `FieldIncompatibility` of `TreeFieldStoredSchema` within two
- * `TreeNodeStoredSchema`. It includes an array of `FieldIncompatibility` instances in the `differences` field.
+ * - NodeFieldsDiscrepancy: Indicates the `FieldDiscrepancy` of `TreeFieldStoredSchema` within two
+ * `TreeNodeStoredSchema`. It includes an array of `FieldDiscrepancy` instances in the `differences` field.
  *
  * When comparing two nodes for compatibility, it only makes sense to compare their fields if the nodes are of
  * the same kind (map, object, leaf).
  *
- * 3. Incompatibility
+ * 3. Discrepancy
  *
- * Incompatibility consists of both `NodeIncompatibility` and `FieldIncompatibility`, representing any kind of
- * schema differences. See {@link getAllowedContentIncompatibilities} for more details about how we process it
+ * Discrepancy consists of both `NodeDiscrepancy` and `FieldDiscrepancy`, representing any kind of
+ * schema differences. See {@link getAllowedContentDiscrepancies} for more details about how we process it
  * and the ordering.
  */
-export type Incompatibility = FieldIncompatibility | NodeIncompatibility;
+export type Discrepancy = FieldDiscrepancy | NodeDiscrepancy;
 
-export type NodeIncompatibility = NodeKindIncompatibility | NodeFieldsIncompatibility;
+export type NodeDiscrepancy = NodeKindDiscrepancy | NodeFieldsDiscrepancy;
 
-export type FieldIncompatibility =
-	| AllowedTypeIncompatibility
-	| FieldKindIncompatibility
-	| ValueSchemaIncompatibility;
+export type FieldDiscrepancy =
+	| AllowedTypeDiscrepancy
+	| FieldKindDiscrepancy
+	| ValueSchemaDiscrepancy;
 
-export interface AllowedTypeIncompatibility {
+export interface AllowedTypeDiscrepancy {
 	identifier: string | undefined; // undefined indicates root field schema
 	mismatch: "allowedTypes";
 	/**
@@ -78,213 +78,159 @@ export interface AllowedTypeIncompatibility {
 	stored: string[];
 }
 
-export interface FieldKindIncompatibility {
+export interface FieldKindDiscrepancy {
 	identifier: string | undefined; // undefined indicates root field schema
 	mismatch: "fieldKind";
 	view: FieldKindIdentifier;
 	stored: FieldKindIdentifier;
 }
 
-export interface ValueSchemaIncompatibility {
+export interface ValueSchemaDiscrepancy {
 	identifier: string;
 	mismatch: "valueSchema";
 	view: ValueSchema | undefined;
 	stored: ValueSchema | undefined;
 }
 
-export interface NodeKindIncompatibility {
+export interface NodeKindDiscrepancy {
 	identifier: string;
 	mismatch: "nodeKind";
 	view: SchemaFactoryNodeKind | undefined;
 	stored: SchemaFactoryNodeKind | undefined;
 }
 
-export interface NodeFieldsIncompatibility {
+export interface NodeFieldsDiscrepancy {
 	identifier: string;
 	mismatch: "fields";
-	differences: FieldIncompatibility[];
+	differences: FieldDiscrepancy[];
 }
 
 type SchemaFactoryNodeKind = "object" | "leaf" | "map";
 
+function getNodeSchemaType(nodeSchema: TreeNodeStoredSchema): SchemaFactoryNodeKind {
+	if (nodeSchema instanceof ObjectNodeStoredSchema) {
+		return "object";
+	} else if (nodeSchema instanceof MapNodeStoredSchema) {
+		return "map";
+	} else if (nodeSchema instanceof LeafNodeStoredSchema) {
+		return "leaf";
+	}
+	throwUnsupportedNodeType(nodeSchema.constructor.name);
+}
+
 /**
- * @remarks
+ * Finds and reports discrepancies between a view schema and a stored schema.
  *
  * The workflow for finding schema incompatibilities:
- * 1. Compare the two root schemas to identify any `FieldIncompatibility`.
+ * 1. Compare the two root schemas to identify any `FieldDiscrepancy`.
  *
  * 2. For each node schema in the `view`:
  * - Verify if the node schema exists in the stored. If it does, ensure that the `SchemaFactoryNodeKind` are
- * consistent. Otherwise this difference is treated as `NodeKindIncompatibility`
+ * consistent. Otherwise this difference is treated as `NodeKindDiscrepancy`
  * - If a node schema with the same identifier exists in both view and stored, and their `SchemaFactoryNodeKind`
- * are consistent, perform a exhaustive validation to identify all `FieldIncompatibility`.
+ * are consistent, perform a exhaustive validation to identify all `FieldDiscrepancy`.
  *
  * 3. For each node schema in the stored, verify if it exists in the view. The overlapping parts were already
  * addressed in the previous step.
  *
  * @returns the discrepancies between two TreeStoredSchema objects
  */
-export function getAllowedContentIncompatibilities(
+export function* getAllowedContentDiscrepancies(
 	view: TreeStoredSchema,
 	stored: TreeStoredSchema,
-): Incompatibility[] {
-	const incompatibilities: Incompatibility[] = [];
-
+): Iterable<Discrepancy> {
 	// check root schema discrepancies
-	incompatibilities.push(
-		...trackFieldDiscrepancies(view.rootFieldSchema, stored.rootFieldSchema),
-	);
-
-	// Verify the existence and type of a node schema given its identifier (key), then determine if
-	// an exhaustive search is necessary.
-	const viewNodeKeys = new Set<TreeNodeSchemaIdentifier>();
-	for (const [key, viewNodeSchema] of view.nodeSchema) {
-		viewNodeKeys.add(key);
-
-		if (viewNodeSchema instanceof ObjectNodeStoredSchema) {
-			if (!stored.nodeSchema.has(key)) {
-				incompatibilities.push({
-					identifier: key,
+	yield* getFieldDiscrepancies(view.rootFieldSchema, stored.rootFieldSchema);
+
+	for (const result of compareMaps(view.nodeSchema, stored.nodeSchema)) {
+		switch (result.type) {
+			case "aExtra": {
+				const viewType = getNodeSchemaType(result.value);
+				yield {
+					identifier: result.key,
 					mismatch: "nodeKind",
-					view: "object",
+					view: viewType,
 					stored: undefined,
-				});
-			} else {
-				const storedNodeSchema = stored.nodeSchema.get(key);
-				assert(
-					storedNodeSchema !== undefined,
-					0x9be /* The storedNodeSchema in stored.nodeSchema should not be undefined */,
-				);
-				if (storedNodeSchema instanceof MapNodeStoredSchema) {
-					incompatibilities.push({
-						identifier: key,
-						mismatch: "nodeKind",
-						view: "object",
-						stored: "map",
-					} satisfies NodeKindIncompatibility);
-				} else if (storedNodeSchema instanceof LeafNodeStoredSchema) {
-					incompatibilities.push({
-						identifier: key,
-						mismatch: "nodeKind",
-						view: "object",
-						stored: "leaf",
-					} satisfies NodeKindIncompatibility);
-				} else if (storedNodeSchema instanceof ObjectNodeStoredSchema) {
-					const differences = trackObjectNodeDiscrepancies(viewNodeSchema, storedNodeSchema);
-					if (differences.length > 0) {
-						incompatibilities.push({
-							identifier: key,
-							mismatch: "fields",
-							differences,
-						} satisfies NodeFieldsIncompatibility);
-					}
-				} else {
-					throwUnsupportedNodeType(storedNodeSchema.constructor.name);
-				}
+				};
+				break;
 			}
-		} else if (viewNodeSchema instanceof MapNodeStoredSchema) {
-			if (!stored.nodeSchema.has(key)) {
-				incompatibilities.push({
-					identifier: key,
+			case "bExtra": {
+				const storedType = getNodeSchemaType(result.value);
+				yield {
+					identifier: result.key,
 					mismatch: "nodeKind",
-					view: "map",
-					stored: undefined,
-				} satisfies NodeKindIncompatibility);
-			} else {
-				const storedNodeSchema = stored.nodeSchema.get(key);
-				assert(
-					storedNodeSchema !== undefined,
-					0x9bf /* The storedNodeSchema in stored.nodeSchema should not be undefined */,
-				);
-				if (storedNodeSchema instanceof ObjectNodeStoredSchema) {
-					incompatibilities.push({
-						identifier: key,
-						mismatch: "nodeKind",
-						view: "map",
-						stored: "object",
-					} satisfies NodeKindIncompatibility);
-				} else if (storedNodeSchema instanceof LeafNodeStoredSchema) {
-					incompatibilities.push({
-						identifier: key,
-						mismatch: "nodeKind",
-						view: "map",
-						stored: "leaf",
-					} satisfies NodeKindIncompatibility);
-				} else if (storedNodeSchema instanceof MapNodeStoredSchema) {
-					incompatibilities.push(
-						...trackFieldDiscrepancies(
-							viewNodeSchema.mapFields,
-							storedNodeSchema.mapFields,
-							key,
-						),
-					);
-				} else {
-					throwUnsupportedNodeType(storedNodeSchema.constructor.name);
-				}
+					view: undefined,
+					stored: storedType,
+				};
+				break;
 			}
-		} else if (viewNodeSchema instanceof LeafNodeStoredSchema) {
-			if (!stored.nodeSchema.has(key)) {
-				incompatibilities.push({
-					identifier: key,
-					mismatch: "nodeKind",
-					view: "leaf",
-					stored: undefined,
-				});
-			} else {
-				const storedNodeSchema = stored.nodeSchema.get(key);
-				assert(
-					storedNodeSchema !== undefined,
-					0x9c0 /* The storedNodeSchema in stored.nodeSchema should not be undefined */,
-				);
-				if (storedNodeSchema instanceof MapNodeStoredSchema) {
-					incompatibilities.push({
-						identifier: key,
-						mismatch: "nodeKind",
-						view: "leaf",
-						stored: "map",
-					} satisfies NodeKindIncompatibility);
-				} else if (storedNodeSchema instanceof ObjectNodeStoredSchema) {
-					incompatibilities.push({
-						identifier: key,
-						mismatch: "nodeKind",
-						view: "leaf",
-						stored: "object",
-					} satisfies NodeKindIncompatibility);
-				} else if (storedNodeSchema instanceof LeafNodeStoredSchema) {
-					if (viewNodeSchema.leafValue !== storedNodeSchema.leafValue) {
-						incompatibilities.push({
-							identifier: key,
-							mismatch: "valueSchema",
-							view: viewNodeSchema.leafValue,
-							stored: storedNodeSchema.leafValue,
-						} satisfies ValueSchemaIncompatibility);
-					}
-				} else {
-					throwUnsupportedNodeType(storedNodeSchema.constructor.name);
-				}
+			case "both": {
+				yield* getNodeDiscrepancies(result.key, result.valueA, result.valueB);
+				break;
 			}
-		} else {
-			throwUnsupportedNodeType(viewNodeSchema.constructor.name);
+			default:
+				break;
 		}
 	}
+}
 
-	for (const [key, storedNodeSchema] of stored.nodeSchema) {
-		if (!viewNodeKeys.has(key)) {
-			incompatibilities.push({
-				identifier: key,
-				mismatch: "nodeKind",
-				view: undefined,
-				stored:
-					storedNodeSchema instanceof MapNodeStoredSchema
-						? "map"
-						: storedNodeSchema instanceof ObjectNodeStoredSchema
-							? "object"
-							: "leaf",
-			} satisfies NodeKindIncompatibility);
-		}
+function* getNodeDiscrepancies(
+	identifier: TreeNodeSchemaIdentifier,
+	view: TreeNodeStoredSchema,
+	stored: TreeNodeStoredSchema,
+): Iterable<Discrepancy> {
+	const viewType = getNodeSchemaType(view);
+	const storedType = getNodeSchemaType(stored);
+	if (viewType !== storedType) {
+		yield {
+			identifier,
+			mismatch: "nodeKind",
+			view: viewType,
+			stored: storedType,
+		};
+		return;
 	}
 
-	return incompatibilities;
+	switch (viewType) {
+		case "object": {
+			const differences = Array.from(
+				trackObjectNodeDiscrepancies(
+					view as ObjectNodeStoredSchema,
+					stored as ObjectNodeStoredSchema,
+				),
+			);
+			if (differences.length > 0) {
+				yield {
+					identifier,
+					mismatch: "fields",
+					differences,
+				} satisfies NodeFieldsDiscrepancy;
+			}
+			break;
+		}
+		case "map":
+			yield* getFieldDiscrepancies(
+				(view as MapNodeStoredSchema).mapFields,
+				(stored as MapNodeStoredSchema).mapFields,
+				identifier,
+			);
+			break;
+		case "leaf": {
+			const viewValue = (view as LeafNodeStoredSchema).leafValue;
+			const storedValue = (stored as LeafNodeStoredSchema).leafValue;
+			if (viewValue !== storedValue) {
+				yield {
+					identifier,
+					mismatch: "valueSchema",
+					view: viewValue,
+					stored: storedValue,
+				};
+			}
+			break;
+		}
+		default:
+			break;
+	}
 }
 
 /**
@@ -292,13 +238,11 @@ export function getAllowedContentIncompatibilities(
  *
  * @param keyOrRoot - If the key is missing, it indicates that this is the root field schema.
  */
-function trackFieldDiscrepancies(
+function* getFieldDiscrepancies(
 	view: TreeFieldStoredSchema,
 	stored: TreeFieldStoredSchema,
 	keyOrRoot?: string,
-): FieldIncompatibility[] {
-	const differences: FieldIncompatibility[] = [];
-
+): Iterable<FieldDiscrepancy> {
 	// Only track the symmetric differences of two sets.
 	const findSetDiscrepancies = (
 		a: TreeTypeSet,
@@ -309,34 +253,30 @@ function trackFieldDiscrepancies(
 		return [aDiff, bDiff];
 	};
 
-	const allowedTypesDiscrepancies = findSetDiscrepancies(view.types, stored.types);
-	if (allowedTypesDiscrepancies[0].length > 0 || allowedTypesDiscrepancies[1].length > 0) {
-		differences.push({
+	const [viewExtra, storedExtra] = findSetDiscrepancies(view.types, stored.types);
+	if (viewExtra.length > 0 || storedExtra.length > 0) {
+		yield {
 			identifier: keyOrRoot,
 			mismatch: "allowedTypes",
-			view: allowedTypesDiscrepancies[0],
-			stored: allowedTypesDiscrepancies[1],
-		} satisfies AllowedTypeIncompatibility);
+			view: viewExtra,
+			stored: storedExtra,
+		} satisfies AllowedTypeDiscrepancy;
 	}
 
 	if (view.kind !== stored.kind) {
-		differences.push({
+		yield {
 			identifier: keyOrRoot,
 			mismatch: "fieldKind",
 			view: view.kind,
 			stored: stored.kind,
-		} satisfies FieldKindIncompatibility);
+		} satisfies FieldKindDiscrepancy;
 	}
-
-	return differences;
 }
 
-function trackObjectNodeDiscrepancies(
+function* trackObjectNodeDiscrepancies(
 	view: ObjectNodeStoredSchema,
 	stored: ObjectNodeStoredSchema,
-): FieldIncompatibility[] {
-	const differences: FieldIncompatibility[] = [];
-	const viewFieldKeys = new Set<FieldKey>();
+): Iterable<FieldDiscrepancy> {
 	/**
 	 * Similar to the logic used for tracking discrepancies between two node schemas, we will identify
 	 * three types of differences:
@@ -348,47 +288,68 @@ function trackObjectNodeDiscrepancies(
 	 * Then, the stored schema is iterated to find the third type.
 	 */
 
-	for (const [fieldKey, fieldStoredSchema] of view.objectNodeFields) {
-		viewFieldKeys.add(fieldKey);
-		if (
-			!stored.objectNodeFields.has(fieldKey) &&
-			fieldStoredSchema.kind !== storedEmptyFieldSchema.kind
-		) {
-			differences.push({
-				identifier: fieldKey,
-				mismatch: "fieldKind",
-				view: fieldStoredSchema.kind,
-				stored: storedEmptyFieldSchema.kind,
-			} satisfies FieldKindIncompatibility);
-		} else {
-			differences.push(
-				...trackFieldDiscrepancies(
-					view.objectNodeFields.get(fieldKey) as TreeFieldStoredSchema,
-					stored.objectNodeFields.get(fieldKey) as TreeFieldStoredSchema,
-					fieldKey,
-				),
-			);
+	for (const result of compareMaps(view.objectNodeFields, stored.objectNodeFields)) {
+		const fieldKey = result.key;
+		switch (result.type) {
+			case "aExtra": {
+				if (result.value.kind === storedEmptyFieldSchema.kind) {
+					// In one of view/stored, this field is explicitly forbidden, but in the other it is implicitly forbidden
+					// (by way of omission). We treat these identically anyway.
+					break;
+				}
+				yield {
+					identifier: fieldKey,
+					mismatch: "fieldKind",
+					view: result.value.kind,
+					stored: storedEmptyFieldSchema.kind,
+				} satisfies FieldKindDiscrepancy;
+				break;
+			}
+			case "bExtra": {
+				if (result.value.kind === storedEmptyFieldSchema.kind) {
+					// In one of view/stored, this field is explicitly forbidden, but in the other it is implicitly forbidden
+					// (by way of omission). We treat these identically anyway.
+					break;
+				}
+				yield {
+					identifier: fieldKey,
+					mismatch: "fieldKind",
+					view: storedEmptyFieldSchema.kind,
+					stored: result.value.kind,
+				} satisfies FieldKindDiscrepancy;
+				break;
+			}
+			case "both": {
+				yield* getFieldDiscrepancies(result.valueA, result.valueB, fieldKey);
+				break;
+			}
+			default: {
+				break;
+			}
 		}
 	}
+}
 
-	for (const [fieldKey, fieldStoredSchema] of stored.objectNodeFields) {
-		if (viewFieldKeys.has(fieldKey)) {
-			continue;
-		}
-
-		if (fieldStoredSchema.kind !== storedEmptyFieldSchema.kind) {
-			differences.push({
-				identifier: fieldKey,
-				mismatch: "fieldKind",
-				view: storedEmptyFieldSchema.kind,
-				stored: fieldStoredSchema.kind,
-			} satisfies FieldKindIncompatibility);
+function* compareMaps<K, V1, V2>(
+	a: ReadonlyMap<K, V1>,
+	b: ReadonlyMap<K, V2>,
+): Iterable<
+	| { type: "aExtra"; key: K; value: V1 }
+	| { type: "bExtra"; key: K; value: V2 }
+	| { type: "both"; key: K; valueA: V1; valueB: V2 }
+> {
+	for (const [key, valueA] of a) {
+		const valueB = b.get(key);
+		yield valueB === undefined
+			? { type: "aExtra", key, value: valueA }
+			: { type: "both", key, valueA, valueB };
+	}
+	for (const [key, valueB] of b) {
+		if (!a.has(key)) {
+			yield { type: "bExtra", key, value: valueB };
 		}
 	}
-
-	return differences;
 }
-
 /**
  * @remarks
  *
@@ -407,12 +368,12 @@ function trackObjectNodeDiscrepancies(
  * validating internal fields.
  */
 export function isRepoSuperset(view: TreeStoredSchema, stored: TreeStoredSchema): boolean {
-	const incompatibilities = getAllowedContentIncompatibilities(view, stored);
+	const discrepancies = getAllowedContentDiscrepancies(view, stored);
 
-	for (const incompatibility of incompatibilities) {
-		switch (incompatibility.mismatch) {
+	for (const discrepancy of discrepancies) {
+		switch (discrepancy.mismatch) {
 			case "nodeKind": {
-				if (incompatibility.stored !== undefined) {
+				if (discrepancy.stored !== undefined) {
 					// It's fine for the view schema to know of a node type that the stored schema doesn't know about.
 					return false;
 				}
@@ -421,15 +382,15 @@ export function isRepoSuperset(view: TreeStoredSchema, stored: TreeStoredSchema)
 			case "valueSchema":
 			case "allowedTypes":
 			case "fieldKind": {
-				if (!validateFieldIncompatibility(incompatibility)) {
+				if (!isFieldDiscrepancyCompatible(discrepancy)) {
 					return false;
 				}
 				break;
 			}
 			case "fields": {
 				if (
-					incompatibility.differences.some(
-						(difference) => !validateFieldIncompatibility(difference),
+					discrepancy.differences.some(
+						(difference) => !isFieldDiscrepancyCompatible(difference),
 					)
 				) {
 					return false;
@@ -442,16 +403,16 @@ export function isRepoSuperset(view: TreeStoredSchema, stored: TreeStoredSchema)
 	return true;
 }
 
-function validateFieldIncompatibility(incompatibility: FieldIncompatibility): boolean {
-	switch (incompatibility.mismatch) {
+function isFieldDiscrepancyCompatible(discrepancy: FieldDiscrepancy): boolean {
+	switch (discrepancy.mismatch) {
 		case "allowedTypes": {
 			// Since we only track the symmetric difference between the allowed types in the view and
 			// stored schemas, it's sufficient to check if any extra allowed types still exist in the
 			// stored schema.
-			return incompatibility.stored.length === 0;
+			return discrepancy.stored.length === 0;
 		}
 		case "fieldKind": {
-			return posetLte(incompatibility.stored, incompatibility.view, fieldRealizer);
+			return posetLte(discrepancy.stored, discrepancy.view, fieldRealizer);
 		}
 		case "valueSchema": {
 			return false;

package/src/feature-libraries/modular-schema/index.ts

@@ -74,4 +74,7 @@ export type {
 	FieldKindConfiguration,
 	FieldKindConfigurationEntry,
 } from "./fieldKindConfiguration.js";
-export { getAllowedContentIncompatibilities, isRepoSuperset } from "./discrepancies.js";
+export {
+	getAllowedContentDiscrepancies,
+	isRepoSuperset,
+} from "./discrepancies.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.10.0-306579";
+export const pkgVersion = "2.10.0-307399";

package/src/shared-tree/treeApi.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { TreeStatus } from "../feature-libraries/index.js";
@@ -464,10 +464,12 @@ function runTransactionInCheckout<TResult>(
 		switch (constraint.type) {
 			case "nodeInDocument": {
 				const node = getOrCreateInnerNode(constraint.node);
-				assert(
-					treeApi.status(constraint.node) === TreeStatus.InDocument,
-					0x90f /* Attempted to apply "nodeExists" constraint when building a transaction, but the node is not in the document. */,
-				);
+				const nodeStatus = treeApi.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;
 			}