@fluidframework/tree 2.52.0 → 2.53.0

package/src/shared-tree/schematizeTree.ts

@@ -3,240 +3,124 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 
-import {
-	CursorLocationType,
-	type ITreeCursorSynchronous,
-	type TreeStoredSchema,
-	rootFieldKey,
-	schemaDataIsEmpty,
-} from "../core/index.js";
+import { type TreeStoredSchema, rootFieldKey, schemaDataIsEmpty } from "../core/index.js";
 import {
 	FieldKinds,
 	allowsRepoSuperset,
-	cursorForMapTreeField,
 	defaultSchemaPolicy,
-	mapTreeFromCursor,
+	type IDefaultEditBuilder,
+	type TreeChunk,
 } from "../feature-libraries/index.js";
-import { toStoredSchema, type SchemaCompatibilityTester } from "../simple-tree/index.js";
-import { isReadonlyArray } from "../util/index.js";
 
 import type { ITreeCheckout } from "./treeCheckout.js";
 
+export function canInitialize(checkout: ITreeCheckout): boolean {
+	// Check for empty.
+	return checkout.forest.isEmpty && schemaDataIsEmpty(checkout.storedSchema);
+}
+
 /**
- * Modify `storedSchema` and invoke `setInitialTree` when it's time to set the tree content.
- *
- * Requires `storedSchema` to be in its default/empty state.
- *
- * This is done in such a way that if the content (implicitly assumed to start empty)
- * is never out of schema.
- * This means that if the root field of the new schema requires content (like a value field),
- * a temporary intermediate schema is used so the initial empty state is not out of schema.
+ * Initialize a checkout with a schema and tree content.
+ * This function should only be called when the tree is uninitialized (no schema or content).
  *
- * Since this makes multiple changes, callers may want to wrap it in a transaction.
+ * @param checkout - The tree checkout to initialize.
+ * @param newSchema - The new schema to apply.
+ * @param contentFactory - A function that sets the initial tree content.
+ * Invoked after a schema containing all nodes from newSchema is applied.
+ * Note that the final root field schema may not have been applied yet: if the root is required, it will be optional at this time
+ * (so the root being empty before the insertion is not out of schema).
+ * @remarks
+ * If `newSchema` is not compatible with the empty tree, this function handles it using an intermediate schema
+ * which supports the empty tree as well as the final tree content.
+ * @privateRemarks
+ * This takes in a checkout using a subset of the checkout interface to enable easier unit testing.
  */
-export function initializeContent(
-	schemaRepository: {
-		storedSchema: ITreeCheckout["storedSchema"];
-		updateSchema: ITreeCheckout["updateSchema"];
-	},
+export function initialize(
+	checkout: Pick<ITreeCheckout, "storedSchema" | "updateSchema">,
 	newSchema: TreeStoredSchema,
 	setInitialTree: () => void,
 ): void {
 	assert(
-		schemaDataIsEmpty(schemaRepository.storedSchema),
+		schemaDataIsEmpty(checkout.storedSchema),
 		0x743 /* cannot initialize after a schema is set */,
 	);
 
-	const rootSchema = newSchema.rootFieldSchema;
-	const rootKind = rootSchema.kind;
-
 	// To keep the data in schema during the update, first define a schema that tolerates the current (empty) tree as well as the final (initial) tree.
-	let incrementalSchemaUpdate: TreeStoredSchema;
-	if (
-		rootKind === FieldKinds.sequence.identifier ||
-		rootKind === FieldKinds.optional.identifier
-	) {
-		// These kinds are known to tolerate empty, so use the schema as is:
-		incrementalSchemaUpdate = newSchema;
-	} else {
-		assert(rootKind === FieldKinds.required.identifier, 0x5c8 /* Unexpected kind */);
-		// Replace value kind with optional kind in root field schema:
-		incrementalSchemaUpdate = {
-			nodeSchema: newSchema.nodeSchema,
-			rootFieldSchema: {
-				kind: FieldKinds.optional.identifier,
-				types: rootSchema.types,
-				persistedMetadata: rootSchema.persistedMetadata,
-			},
-		};
+	let intermediateSchema: TreeStoredSchema;
+	{
+		const rootSchema = newSchema.rootFieldSchema;
+		const rootKind = rootSchema.kind;
+		if (
+			rootKind === FieldKinds.sequence.identifier ||
+			rootKind === FieldKinds.optional.identifier
+		) {
+			// These kinds are known to tolerate empty, so use the schema as is:
+			intermediateSchema = newSchema;
+		} else {
+			assert(rootKind === FieldKinds.required.identifier, 0x5c8 /* Unexpected kind */);
+			// Replace value kind with optional kind in root field schema:
+			intermediateSchema = {
+				nodeSchema: newSchema.nodeSchema,
+				rootFieldSchema: {
+					kind: FieldKinds.optional.identifier,
+					types: rootSchema.types,
+					persistedMetadata: rootSchema.persistedMetadata,
+				},
+			};
+		}
 	}
 
 	assert(
-		allowsRepoSuperset(defaultSchemaPolicy, newSchema, incrementalSchemaUpdate),
+		allowsRepoSuperset(defaultSchemaPolicy, newSchema, intermediateSchema),
 		0x5c9 /* Incremental Schema during update should allow a superset of the final schema */,
 	);
-	// Update to intermediate schema
-	schemaRepository.updateSchema(incrementalSchemaUpdate);
-	// Insert initial tree
+
+	checkout.updateSchema(intermediateSchema);
 	setInitialTree();
 
 	// If intermediate schema is not final desired schema, update to the final schema:
-	if (incrementalSchemaUpdate !== newSchema) {
+	if (intermediateSchema !== newSchema) {
 		// This makes the root more strict, so set allowNonSupersetSchema to true.
-		schemaRepository.updateSchema(newSchema, true);
+		checkout.updateSchema(newSchema, true);
 	}
 }
 
-export enum UpdateType {
-	/**
-	 * Already compatible, no update needed.
-	 */
-	None,
-	/**
-	 * Schema can be upgraded leaving tree as is.
-	 */
-	SchemaCompatible,
-	/**
-	 * No update currently supported.
-	 */
-	Incompatible,
-}
-
 /**
- * Returns how compatible updating checkout's schema is with the viewSchema.
- */
-export function evaluateUpdate(
-	viewSchema: SchemaCompatibilityTester,
-	checkout: ITreeCheckout,
-): UpdateType {
-	const compatibility = viewSchema.checkCompatibility(checkout.storedSchema);
-
-	if (compatibility.canUpgrade && compatibility.canView) {
-		// Compatible as is
-		return UpdateType.None;
-	}
-
-	if (!compatibility.canUpgrade) {
-		// Existing stored schema permits trees which are incompatible with the view schema, so schema can not be updated
-		return UpdateType.Incompatible;
-	}
-
-	assert(!compatibility.canView, 0x8bd /* unexpected case */);
-	assert(compatibility.canUpgrade, 0x8be /* unexpected case */);
-
-	return UpdateType.SchemaCompatible;
-}
-
-export function canInitialize(checkout: ITreeCheckout): boolean {
-	// Check for empty.
-	return checkout.forest.isEmpty && schemaDataIsEmpty(checkout.storedSchema);
-}
-
-function normalizeNewFieldContent(
-	content: readonly ITreeCursorSynchronous[] | ITreeCursorSynchronous | undefined,
-): ITreeCursorSynchronous {
-	if (content === undefined) {
-		return cursorForMapTreeField([]);
-	}
-
-	if (isReadonlyArray(content)) {
-		return cursorForMapTreeField(content.map((c) => mapTreeFromCursor(c)));
-	}
-
-	if (content.mode === CursorLocationType.Fields) {
-		return content;
-	}
-
-	return cursorForMapTreeField([mapTreeFromCursor(content)]);
-}
-
-/**
- * Initialize a checkout with a schema and tree content.
- * This function should only be called when the tree is uninitialized (no schema or content).
- * @remarks
- *
- * If the proposed schema (from `treeContent`) is not compatible with the empty tree, this function handles using an intermediate schema
- * which supports the empty tree as well as the final tree content.
- */
-export function initialize(checkout: ITreeCheckout, treeContent: TreeStoredContent): void {
-	checkout.transaction.start();
-	try {
-		initializeContent(checkout, treeContent.schema, () => {
-			const field = { field: rootFieldKey, parent: undefined };
-			const content = normalizeNewFieldContent(treeContent.initialTree);
-			const contentChunk = checkout.forest.chunkField(content);
-
-			switch (checkout.storedSchema.rootFieldSchema.kind) {
-				case FieldKinds.optional.identifier: {
-					const fieldEditor = checkout.editor.optionalField(field);
-					assert(
-						content.getFieldLength() <= 1,
-						0x7f4 /* optional field content should normalize at most one item */,
-					);
-					fieldEditor.set(contentChunk.topLevelLength === 0 ? undefined : contentChunk, true);
-					break;
-				}
-				case FieldKinds.sequence.identifier: {
-					const fieldEditor = checkout.editor.sequenceField(field);
-					// TODO: should do an idempotent edit here.
-					fieldEditor.insert(0, contentChunk);
-					break;
-				}
-				default: {
-					fail(0xac7 /* unexpected root field kind during initialize */);
-				}
-			}
-		});
-	} finally {
-		checkout.transaction.commit();
-	}
-}
-
-/**
- * Ensure a {@link ITreeCheckout} can be used with a given {@link SchemaCompatibilityTester}.
- *
+ * Construct a general purpose `setInitialTree` for use with {@link initialize} from a function that returns a chunk.
+ * @param contentFactory - A function that returns the initial tree content as a chunk.
+ * Invoked after a schema containing all nodes from newSchema is applied.
+ * Note that the final root field schema may not have been applied yet: if the root is required, it will be optional at this time
+ * (so the root being empty before the insertion is not out of schema).
  * @remarks
- * It is up to the caller to ensure that compatibility is reevaluated if the checkout's stored schema is edited in the future.
- *
- * @param viewSchema - View schema that `checkout` should be made compatible with.
- * @param allowedSchemaModifications - Flags enum describing the ways this is allowed to modify `checkout`.
- * @param checkout - To be modified as needed to be compatible with `viewSchema`.
- * @param treeContent - Content to be used to initialize `checkout`'s the tree if needed and allowed.
- * @returns true iff checkout now is compatible with `viewSchema`.
+ * This does not support sequence roots as they are not allowed in the public API surface.
+ * A test utility for them can be found as `initializeSequenceRoot` for testing internal logic which uses a sequence root.
  */
-export function ensureSchema(
-	viewSchema: SchemaCompatibilityTester,
-	checkout: ITreeCheckout,
-): boolean {
-	const updatedNeeded = evaluateUpdate(viewSchema, checkout);
-	switch (updatedNeeded) {
-		case UpdateType.None: {
-			return true;
-		}
-		case UpdateType.Incompatible: {
-			return false;
-		}
-		case UpdateType.SchemaCompatible: {
-			checkout.updateSchema(toStoredSchema(viewSchema.viewSchema.root));
-			return true;
-		}
-		default: {
-			unreachableCase(updatedNeeded);
-		}
-	}
+export function initializerFromChunk(
+	checkout: Pick<ITreeCheckout, "storedSchema"> & {
+		readonly editor: IDefaultEditBuilder;
+	},
+	contentFactory: () => TreeChunk,
+): () => void {
+	return () => initializeFromChunk(checkout, contentFactory());
 }
 
-/**
- * Content that can populate a `SharedTree`.
- */
-export interface TreeStoredContent {
-	readonly schema: TreeStoredSchema;
-
-	/**
-	 * Default tree content to initialize the tree with iff the tree is uninitialized
-	 * (meaning it does not even have any schema set at all).
-	 */
-	readonly initialTree: readonly ITreeCursorSynchronous[] | ITreeCursorSynchronous | undefined;
+function initializeFromChunk(
+	checkout: Pick<ITreeCheckout, "storedSchema"> & {
+		readonly editor: IDefaultEditBuilder;
+	},
+	contentChunk: TreeChunk,
+): void {
+	const field = { field: rootFieldKey, parent: undefined };
+	assert(
+		checkout.storedSchema.rootFieldSchema.kind === FieldKinds.optional.identifier,
+		0xc11 /* initializerFromChunk only supports optional roots */,
+	);
+	const fieldEditor = checkout.editor.optionalField(field);
+	assert(
+		contentChunk.topLevelLength <= 1,
+		0x7f4 /* optional field content should normalize at most one item */,
+	);
+	fieldEditor.set(contentChunk.topLevelLength === 0 ? undefined : contentChunk, true);
 }

package/src/shared-tree/schematizingTreeView.ts

@@ -16,7 +16,7 @@ import { anchorSlot } from "../core/index.js";
 import {
 	type NodeIdentifierManager,
 	defaultSchemaPolicy,
-	cursorForMapTreeNode,
+	cursorForMapTreeField,
 	TreeStatus,
 	Context,
 } from "../feature-libraries/index.js";
@@ -51,10 +51,11 @@ import {
 	areImplicitFieldSchemaEqual,
 	prepareForInsertionContextless,
 	type FieldSchema,
-	toStoredSchema,
 	tryDisposeTreeNode,
 	FieldSchemaAlpha,
 	TreeViewConfigurationAlpha,
+	toInitialSchema,
+	toUpgradeSchema,
 } from "../simple-tree/index.js";
 import {
 	type Breakable,
@@ -63,7 +64,7 @@ import {
 	type WithBreakable,
 } from "../util/index.js";
 
-import { canInitialize, ensureSchema, initialize } from "./schematizeTree.js";
+import { canInitialize, initialize, initializerFromChunk } from "./schematizeTree.js";
 import type { ITreeCheckout, TreeCheckout } from "./treeCheckout.js";
 
 /**
@@ -172,7 +173,7 @@ export class SchematizingSimpleTreeView<
 		}
 
 		this.runSchemaEdit(() => {
-			const schema = toStoredSchema(this.config.schema);
+			const schema = toInitialSchema(this.config.schema);
 			const mapTree = prepareForInsertionContextless(
 				content as InsertableContent | undefined,
 				this.rootFieldSchema,
@@ -181,12 +182,22 @@ export class SchematizingSimpleTreeView<
 					policy: defaultSchemaPolicy,
 				},
 				this,
+				schema.rootFieldSchema,
 			);
 
-			initialize(this.checkout, {
+			this.checkout.transaction.start();
+
+			initialize(
+				this.checkout,
 				schema,
-				initialTree: mapTree === undefined ? undefined : cursorForMapTreeNode(mapTree),
-			});
+				initializerFromChunk(this.checkout, () => {
+					// This must be done after initial schema is set!
+					return this.checkout.forest.chunkField(
+						cursorForMapTreeField(mapTree === undefined ? [] : [mapTree]),
+					);
+				}),
+			);
+			this.checkout.transaction.commit();
 		});
 	}
 
@@ -205,10 +216,8 @@ export class SchematizingSimpleTreeView<
 			);
 		}
 
-		this.runSchemaEdit(() => {
-			const result = ensureSchema(this.viewSchema, this.checkout);
-			assert(result, 0x8bf /* Schema upgrade should always work if canUpgrade is set. */);
-		});
+		const newSchema = toUpgradeSchema(this.viewSchema.viewSchema.root);
+		this.runSchemaEdit(() => this.checkout.updateSchema(newSchema));
 	}
 
 	/**
@@ -436,7 +445,12 @@ export class SchematizingSimpleTreeView<
 			);
 		}
 		const view = this.getFlexTreeContext();
-		setField(view.root, this.rootFieldSchema, newRoot as InsertableContent | undefined);
+		setField(
+			view.root,
+			this.rootFieldSchema,
+			newRoot as InsertableContent | undefined,
+			this.checkout.storedSchema.rootFieldSchema,
+		);
 	}
 
 	// #region Branching

package/src/shared-tree/treeAlpha.ts

@@ -36,7 +36,6 @@ import {
 	verboseFromCursor,
 	type TreeEncodingOptions,
 	type VerboseTree,
-	toStoredSchema,
 	extractPersistedSchema,
 	type TreeBranch,
 	TreeViewConfigurationAlpha,
@@ -52,6 +51,9 @@ import {
 	tryGetTreeNodeForField,
 	isObjectNodeSchema,
 	isTreeNode,
+	toInitialSchema,
+	convertField,
+	toUnhydratedSchema,
 } from "../simple-tree/index.js";
 import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import {
@@ -493,7 +495,11 @@ export const TreeAlpha: TreeAlpha = {
 			return undefined as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 		}
 		const cursor = cursorFromVerbose(data, schemalessConfig);
-		return createFromCursor(schema, cursor);
+		return createFromCursor(
+			schema,
+			cursor,
+			convertField(normalizeFieldSchema(schema), toUnhydratedSchema),
+		);
 	},
 
 	exportConcise,
@@ -523,11 +529,18 @@ export const TreeAlpha: TreeAlpha = {
 		const batch: FieldBatch = [cursor];
 		// If none provided, create a compressor which will not compress anything.
 		const idCompressor = options.idCompressor ?? createIdCompressor();
+
+		// Grabbing an existing stored schema from the node is important to ensure that unknown optional fields can be preserved.
+		// Note that if the node is unhydrated, this can result in all staged allowed types being included in the schema, which might be undesired.
+		const storedSchema = isTreeNode(node)
+			? getKernel(node).context.flexContext.schema
+			: toInitialSchema(schema);
+
 		const context: FieldBatchEncodingContext = {
 			encodeType: TreeCompressionStrategy.Compressed,
 			idCompressor,
 			originatorId: idCompressor.localSessionId, // TODO: Why is this needed?
-			schema: { schema: toStoredSchema(schema), policy: defaultSchemaPolicy },
+			schema: { schema: storedSchema, policy: defaultSchemaPolicy },
 		};
 		const result = codec.encode(batch, context);
 		return result;
@@ -543,7 +556,8 @@ export const TreeAlpha: TreeAlpha = {
 		const config = new TreeViewConfigurationAlpha({ schema });
 		const content: ViewContent = {
 			// Always use a v1 schema codec for consistency.
-			schema: extractPersistedSchema(config, FluidClientVersion.v2_0),
+			// TODO: reevaluate how staged schema should behave in schema import/export APIs before stabilizing this.
+			schema: extractPersistedSchema(config.schema, FluidClientVersion.v2_0, () => true),
 			tree: compressedData,
 			idCompressor: options.idCompressor ?? createIdCompressor(),
 		};

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

@@ -14,7 +14,8 @@ import {
 import type { GraphCommit, TaggedChange } from "../core/index.js";
 import { disposeSymbol, hasSome } from "../util/index.js";
 
-import type { ChangeEnricherReadonlyCheckout, ResubmitMachine } from "./index.js";
+import type { ChangeEnricherReadonlyCheckout } from "./changeEnricher.js";
+import type { ResubmitMachine } from "./resubmitMachine.js";
 
 interface PendingChange<TChange> {
 	commit: GraphCommit<TChange>;

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

@@ -25,7 +25,11 @@ import {
 	evaluateLazySchema,
 	markSchemaMostDerived,
 } from "../core/index.js";
-import { toStoredSchema } from "../toStoredSchema.js";
+import {
+	permissiveStoredSchemaGenerationOptions,
+	restrictiveStoredSchemaGenerationOptions,
+	toStoredSchema,
+} from "../toStoredSchema.js";
 import {
 	isArrayNodeSchema,
 	isMapNodeSchema,
@@ -161,6 +165,9 @@ export interface ITreeViewConfiguration<
 
 /**
  * Configuration for {@link ViewableTree.viewWith}.
+ * @privateRemarks
+ * When `ImplicitAnnotatedFieldSchema` is stabilized, TSchema should be updated to use it.
+ * When doing this, the example for `staged` will need to be updated/simplified.
  * @sealed @public
  */
 export class TreeViewConfiguration<
@@ -213,7 +220,8 @@ export class TreeViewConfiguration<
 
 		// Eagerly perform this conversion to surface errors sooner.
 		// Includes detection of duplicate schema identifiers.
-		toStoredSchema(config.schema);
+		toStoredSchema(config.schema, restrictiveStoredSchemaGenerationOptions);
+		toStoredSchema(config.schema, permissiveStoredSchemaGenerationOptions);
 
 		const definitions = new Map<string, SimpleNodeSchema & TreeNodeSchema>();
 

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

@@ -13,12 +13,9 @@ import {
 	mapCursorFields,
 	type ITreeCursorSynchronous,
 	type SchemaAndPolicy,
+	type TreeFieldStoredSchema,
 } from "../../core/index.js";
-import {
-	normalizeFieldSchema,
-	type ImplicitFieldSchema,
-	type TreeFieldFromImplicitField,
-} from "../fieldSchema.js";
+import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../fieldSchema.js";
 import {
 	type Context,
 	getOrCreateNodeFromInnerNode,
@@ -32,33 +29,31 @@ import {
 	throwOutOfSchema,
 } from "../../feature-libraries/index.js";
 import { getUnhydratedContext } from "../createContext.js";
-import { convertField } from "../toStoredSchema.js";
 import { unknownTypeError } from "./customTree.js";
 
 /**
  * Creates an unhydrated simple-tree field from a cursor in nodes mode.
  * @remarks
  * Does not support providing missing defaults values.
- * Validates the field is in schema using the provided `contextForNewNodes` of the default unhydrated context if not provided.
+ * Validates the field is in schema using `destinationSchema` the provided `contextForNewNodes` or the default unhydrated context if not provided.
  */
 export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 	schema: TSchema,
 	cursor: ITreeCursorSynchronous | undefined,
+	destinationSchema: TreeFieldStoredSchema,
 	contextForNewNodes?: Context,
 ): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
 	const context = contextForNewNodes ?? getUnhydratedContext(schema);
 	assert(context.flexContext.isHydrated() === false, 0xbfe /* Expected unhydrated context */);
 	const mapTrees = cursor === undefined ? [] : [unhydratedFlexTreeFromCursor(context, cursor)];
 
-	const rootFieldSchema = convertField(normalizeFieldSchema(schema));
-
 	const schemaAndPolicy: SchemaAndPolicy = {
 		policy: defaultSchemaPolicy,
 		schema: context.flexContext.schema,
 	};
 
 	// Assuming the caller provides the correct `contextForNewNodes`, this should handle unknown optional fields.
-	isFieldInSchema(mapTrees, rootFieldSchema, schemaAndPolicy, throwOutOfSchema);
+	isFieldInSchema(mapTrees, destinationSchema, schemaAndPolicy, throwOutOfSchema);
 
 	if (mapTrees.length === 0) {
 		return undefined as Unhydrated<TreeFieldFromImplicitField<TSchema>>;

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

@@ -89,11 +89,13 @@ export interface FieldDiscrepancyLocation {
 export interface AllowedTypeDiscrepancy extends FieldDiscrepancyLocation {
 	readonly mismatch: "allowedTypes";
 	/**
-	 * List of annotated allowed types in viewed schema which are not allowed in stored schema
+	 * Annotated allowed types in viewed schema
+	 * (excluding {@link SchemaStaticsAlpha.staged | staged} schema) which are not allowed in stored schema.
 	 */
 	readonly view: readonly AnnotatedAllowedType<TreeNodeSchema>[];
 	/**
-	 * List of allowed type identifiers in stored schema which are not allowed in view schema
+	 * Allowed type identifiers in stored schema which are not allowed in view schema
+	 * (including the view schema's {@link SchemaStaticsAlpha.staged | staged} schema).
 	 */
 	readonly stored: readonly TreeNodeSchemaIdentifier[];
 }
@@ -296,28 +298,28 @@ function* getNodeDiscrepancies(
 
 /**
  * Returns the allowed types that are not present in both the given view and stored schemas.
- * It returns a tuple containing two arrays:
- * 1. The first array contains the allowed types that are present in the view schema but not in the stored schema.
- * 2. The second array contains the allowed types that are present in the stored schema but not in the view schema.
  */
 export function findExtraAllowedTypes(
 	viewAllowedTypes: readonly AnnotatedAllowedType<TreeNodeSchema>[],
 	storedAllowedTypes: TreeTypeSet,
-): {
-	viewExtra: readonly AnnotatedAllowedType<TreeNodeSchema>[];
-	storedExtra: TreeNodeSchemaIdentifier[];
-} {
+): Pick<AllowedTypeDiscrepancy, "view" | "stored"> {
 	const viewNodeSchemaIdentifiers = new Set(
 		viewAllowedTypes.map((value) => value.type.identifier),
 	);
 
-	const viewExtra = viewAllowedTypes.filter(
-		(value) => !storedAllowedTypes.has(brand(value.type.identifier)),
+	// TODO:
+	// Add detecting which SchemaUpgrades have been made.
+	// When doing so, each will fall into one of three states: staged, partially applied, or fully applied.
+	// This would allow for nicer compatibility errors and more detailed compatibility status in the future.
+	const view = viewAllowedTypes.filter(
+		(value) =>
+			!storedAllowedTypes.has(brand(value.type.identifier)) &&
+			value.metadata.stagedSchemaUpgrade === undefined,
 	);
-	const storedExtra = [...storedAllowedTypes].filter(
+	const stored = [...storedAllowedTypes].filter(
 		(value) => !viewNodeSchemaIdentifiers.has(value),
 	);
-	return { viewExtra, storedExtra };
+	return { view, stored };
 }
 
 /**
@@ -384,14 +386,13 @@ function* getAllowedTypeDiscrepancies(
 	identifier: TreeNodeSchemaIdentifier | undefined,
 	fieldKey: FieldKey | undefined,
 ): Iterable<FieldDiscrepancy> {
-	const { viewExtra, storedExtra } = findExtraAllowedTypes(view, stored);
-	if (viewExtra.length > 0 || storedExtra.length > 0) {
+	const discrepancies = findExtraAllowedTypes(view, stored);
+	if (discrepancies.view.length > 0 || discrepancies.stored.length > 0) {
 		yield {
+			...discrepancies,
 			identifier,
 			fieldKey,
 			mismatch: "allowedTypes",
-			view: viewExtra,
-			stored: storedExtra,
 		} satisfies AllowedTypeDiscrepancy;
 	}
 }

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

@@ -24,16 +24,15 @@ export type {
 	ITreeAlpha,
 } from "./tree.js";
 export { asTreeViewAlpha } from "./tree.js";
+export { type SchemaStatics, schemaStatics } from "./schemaStatics.js";
 export {
 	SchemaFactory,
 	type ScopedSchemaName,
 	type SchemaFactoryObjectOptions,
-	type SchemaStatics,
-	schemaStatics,
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
 } from "./schemaFactory.js";
-export { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
+export { SchemaFactoryAlpha, type SchemaStaticsAlpha } from "./schemaFactoryAlpha.js";
 export type {
 	ValidateRecursiveSchema,
 	FixRecursiveArraySchema,