@fluidframework/tree 2.74.0-365691 → 2.74.0

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

@@ -3,31 +3,19 @@
  * Licensed under the MIT License.
  */
 
-import {
-	assert,
-	debugAssert,
-	fail,
-	oob,
-	unreachableCase,
-} from "@fluidframework/core-utils/internal";
+import { assert, fail, oob, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import {
-	type FieldSchemaAlpha,
-	type ImplicitFieldSchema,
-	FieldKind,
-	normalizeFieldSchema,
-} from "../fieldSchema.js";
+import { type FieldSchemaAlpha, type ImplicitFieldSchema, FieldKind } from "../fieldSchema.js";
 import {
 	type AllowedTypesFullEvaluated,
 	NodeKind,
 	type TreeNodeSchema,
-	markSchemaMostDerived,
 } from "../core/index.js";
 import {
-	permissiveStoredSchemaGenerationOptions,
-	restrictiveStoredSchemaGenerationOptions,
-	toStoredSchema,
+	toInitialSchema,
+	toUnhydratedSchema,
+	transformSimpleSchema,
 } from "../toStoredSchema.js";
 import {
 	isArrayNodeSchema,
@@ -42,7 +30,8 @@ import {
 import { getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
-import type { SimpleNodeSchema, SimpleTreeSchema } from "../simpleSchema.js";
+import type { SchemaType, SimpleNodeSchema } from "../simpleSchema.js";
+import { createTreeSchema, type TreeSchema } from "../treeSchema.js";
 
 /**
  * Options when constructing a tree view.
@@ -187,11 +176,6 @@ export class TreeViewConfiguration<
 	 */
 	public readonly preventAmbiguity!: boolean;
 
-	/**
-	 * {@link TreeSchema.definitions} but with public types.
-	 */
-	protected readonly definitionsInternal!: ReadonlyMap<string, TreeNodeSchema>;
-
 	/**
 	 * Construct a new {@link TreeViewConfiguration}.
 	 *
@@ -225,23 +209,10 @@ export class TreeViewConfiguration<
 		// Ambiguity errors are lower priority to report than invalid schema errors, so collect these in an array and report them all at once.
 		const ambiguityErrors: string[] = [];
 
-		// Eagerly perform this conversion to surface errors sooner.
-		// Includes detection of duplicate schema identifiers.
-		toStoredSchema(config.schema, restrictiveStoredSchemaGenerationOptions);
-		toStoredSchema(config.schema, permissiveStoredSchemaGenerationOptions);
-
-		const definitions = new Map<string, SimpleNodeSchema & TreeNodeSchema>();
-
+		// Validate the schema and collect ambiguity errors.
+		// This does a lot of validation (throwing usage errors as a side effect) in addition to just collecting ambiguity errors.
+		// ambiguityErrors are considered a lower priority, so only thrown if no other errors are found.
 		walkFieldSchema(config.schema, {
-			node: (schema) => {
-				// Ensure all reachable schema are marked as most derived.
-				// This ensures if multiple schema extending the same schema factory generated class are present (or have had instances of them constructed, or get instances of them constructed in the future),
-				// an error is reported.
-				markSchemaMostDerived(schema, true);
-
-				debugAssert(() => !definitions.has(schema.identifier));
-				definitions.set(schema.identifier, schema as SimpleNodeSchema & TreeNodeSchema);
-			},
 			allowedTypes({ types }: AllowedTypesFullEvaluated): void {
 				checkUnion(
 					types.map((t) => t.type),
@@ -251,8 +222,6 @@ export class TreeViewConfiguration<
 			},
 		});
 
-		this.definitionsInternal = definitions;
-
 		if (ambiguityErrors.length !== 0) {
 			// Duplicate errors are common since when two types conflict, both orders error:
 			const deduplicated = new Set(ambiguityErrors);
@@ -273,38 +242,22 @@ export class TreeViewConfigurationAlpha<
 	extends TreeViewConfiguration<TSchema>
 	implements TreeSchema
 {
-	/**
-	 * {@inheritDoc TreeSchema.root}
-	 */
 	public readonly root: FieldSchemaAlpha;
-
-	/**
-	 * {@inheritDoc TreeSchema.definitions}
-	 */
-	public get definitions(): ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema> {
-		return this.definitionsInternal as ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
-	}
+	public readonly definitions: ReadonlyMap<
+		string,
+		SimpleNodeSchema<SchemaType.View> & TreeNodeSchema
+	>;
 
 	public constructor(props: ITreeViewConfiguration<TSchema>) {
 		super(props);
-		this.root = normalizeFieldSchema(props.schema);
-	}
-}
+		const treeSchema = createTreeSchema(this.schema);
+		this.root = treeSchema.root;
+		this.definitions = treeSchema.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>;
+		// Eagerly perform these conversions to surface errors sooner.
+		toInitialSchema(this.root);
+		transformSimpleSchema(treeSchema, toUnhydratedSchema);
+	}
 }
 
 /**

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

@@ -23,6 +23,10 @@ import type { ImplicitFieldSchema } from "../fieldSchema.js";
  * * "new": The node was added.
  * * "changed": A direct child was updated, added, removed, or moved (and the node is not "new").
  * * "moved": The node was moved between/within arrays (and the node is not "new" or "changed").
+ * @privateRemarks
+ * It is unclear how this will handle forward compatibility with other kinds of edits, like moves that are not limited to arrays (attach, detach, swap):
+ * this needs to be sorted out before this is stabilized.
+ * It is also unclear how this is supposed to handle schema changes (which can result in new TreeNode instance, but I think won't trigger "new" here).
  * @alpha
  */
 export type DirtyTreeStatus = "new" | "changed" | "moved";
@@ -51,6 +55,13 @@ export interface DirtyTreeMap {
  * console.log(`The root of the tree is ${dirty.get(view.root) ?? "unchanged"}`);
  * stopTracking();
  * ```
+ * @privateRemarks
+ * This provides an opportunity for user code ("set" on dirty) to run during forest changes, in the middle of processing an edit.
+ * We have generally avoided exposing such times to users and instead flush events after the edit has finished and user facing invariants are known to be restored.
+ * Before stabilizing, how this event relates to other events time/ordering wise should be clarified, and if any APIs have been provided to defer events, that mentioned as well.
+ * Maybe updates should be deferred?
+ *
+ * This is also documented in terms of "forest" which is not a concept in the public API, and thus needs to be redefined in terms of public concepts.
  * @alpha
  */
 export function trackDirtyNodes(

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

@@ -43,7 +43,7 @@ import {
 	type FieldSchema,
 } from "../fieldSchema.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
-import type { TreeSchema } from "./configuration.js";
+import type { TreeSchema } from "../treeSchema.js";
 import { tryStoredSchemaAsArray } from "./customTree.js";
 import { FieldKinds } from "../../feature-libraries/index.js";
 

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

@@ -0,0 +1,123 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type {
+	TreeNode,
+	TreeNodeSchema,
+	NodeKind,
+	TreeNodeSchemaClass,
+	WithType,
+} from "../core/index.js";
+
+/**
+ * Type-erase details of a schema.
+ *
+ * @typeParam TNode - The type to narrow the node to.
+ * Typically {@link TreeNode} intersected with the public interface for the component.
+ * @typeParam ExtraSchemaProperties - Properties of the schema (statics on the schema class) to retain in addition to the basic {@link TreeNodeSchema}.
+ * Typically includes at least one static factory method for creating nodes.
+ * @remarks
+ * This can be used to type erase the details of a schema including the node's type (such as its fields and APIs for modifying those fields).
+ * This is intended for use on component boundaries to support encapsulation of implementation details, including the exact schema.
+ *
+ * This is best applied to a top level "component node" which wraps the actual component content (in a single required object node field) allowing more cases of schema evolution to be carried out as implementation details of the component.
+ *
+ * Since this type-erases the schema details, the remaining API will need to provide ways to construct instances of the node and access its contents.
+ * Typically construction is done via static functions on the schema which can be included in `ExtraSchemaProperties`,
+ * and access to contents is done via properties of TNode (usually methods).
+ *
+ * @example
+ * ```typescript
+ * const schema = new SchemaFactory("com.example");
+ *
+ * interface SquareNode {
+ * 	readonly area: number;
+ * }
+ *
+ * interface SquareSchema {
+ * 	create(sideLength: number): Square;
+ * }
+ *
+ * class SquareInternal
+ * 	extends schema.object("Demo", { hidden: schema.number })
+ * 	implements SquareNode
+ * {
+ * 	public get area(): number {
+ * 		return this.hidden * this.hidden;
+ * 	}
+ *
+ * 	public static create(sideLength: number): SquareInternal {
+ * 		return new SquareInternal({ hidden: sideLength });
+ * 	}
+ * }
+ *
+ * const Square = eraseSchemaDetails<Square, SquareSchema>()(SquareInternal);
+ * type Square = SquareNode & TreeNode & WithType<"com.example.Demo">;
+ * ```
+ * @privateRemarks
+ * See "example" test for an executable version of this example.
+ * @alpha
+ */
+export function eraseSchemaDetails<TNode, ExtraSchemaProperties = unknown>(): <
+	T extends ExtraSchemaProperties & TreeNodeSchema<string, NodeKind, TNode & TreeNode>,
+>(
+	schema: T,
+) => ExtraSchemaProperties &
+	TreeNodeSchema<
+		T["identifier"],
+		NodeKind,
+		TNode & TreeNode & WithType<T["identifier"]>,
+		never,
+		false
+	> {
+	return (schema) => schema as never;
+}
+
+/**
+ * Like {@link eraseSchemaDetails} but allows the returned schema to be subclassed.
+ * @example
+ * ```typescript
+ * const schema = new SchemaFactory("com.example");
+ *
+ * interface SquareInterface {
+ * 	readonly area: number;
+ * }
+ *
+ * class SquareInternal
+ * 	extends schema.object("Demo", { size: schema.number })
+ * 	implements SquareInterface
+ * {
+ * 	public get area(): number {
+ * 		return this.size * this.size;
+ * 	}
+ * }
+ *
+ * class Square extends eraseSchemaDetailsSubclassable<SquareInterface>()(SquareInternal) {
+ * 	public static create(sideLength: number): Square {
+ * 		return new (this as TreeNodeSchema as typeof SquareInternal)({ size: sideLength });
+ * 	}
+ * }
+ *
+ * const square = Square.create(10);
+ * assert.equal(square.area, 100);
+ * ```
+ * @privateRemarks
+ * See "example" test for an executable version of this example.
+ * @alpha
+ */
+export function eraseSchemaDetailsSubclassable<TNode, ExtraSchemaProperties = unknown>(): <
+	T extends ExtraSchemaProperties & TreeNodeSchemaClass<string, NodeKind, TNode & TreeNode>,
+>(
+	schema: T,
+) => ExtraSchemaProperties &
+	TreeNodeSchemaClass<
+		T["identifier"],
+		NodeKind,
+		TNode & TreeNode & WithType<T["identifier"]>,
+		never,
+		false
+	> {
+	return (schema) => schema as never;
+}

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

@@ -3,13 +3,14 @@
  * Licensed under the MIT License.
  */
 
+import { Unchanged } from "../core/index.js";
 import type { ImplicitFieldSchema } from "../fieldSchema.js";
-import type { SimpleTreeSchema } from "../simpleSchema.js";
-
-import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
+import type { SchemaType, SimpleTreeSchema } from "../simpleSchema.js";
+import { transformSimpleSchema } from "../toStoredSchema.js";
+import { createTreeSchema } from "../treeSchema.js";
 
 /**
- * Copies data from {@link ImplicitFieldSchema} to create  a {@link SimpleTreeSchema} out of new plain JavaScript objects, Sets and Maps.
+ * Copies data from {@link ImplicitFieldSchema} to create a {@link SimpleTreeSchema} out of new plain JavaScript objects, Sets and Maps.
  *
  * @remarks
  * See also {@link TreeViewConfigurationAlpha} which implements {@link SimpleTreeSchema} as a way to get a `SimpleTreeSchema` without copying the node and field schema and without losing as much type information.
@@ -23,6 +24,12 @@ import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
  *
  * @alpha
  */
-export function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema {
-	return toSimpleTreeSchema(schema, true);
+export function getSimpleSchema(
+	schema: ImplicitFieldSchema,
+): SimpleTreeSchema<SchemaType.View> {
+	// Convert the input into a TreeSchema: This API should probably be updated to take in a TreeSchema directly
+	// (and maybe a clean way to make TreeSchema from ImplicitFieldSchema other than TreeViewConfigurationAlpha should be provided).
+	const treeSchema = createTreeSchema(schema);
+	// Do the actual copy into clean simple schema objects.
+	return transformSimpleSchema(treeSchema, Unchanged);
 }

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

@@ -4,12 +4,13 @@
  */
 
 import { getTreeNodeSchemaPrivateData, type AllowedTypesFull } from "../core/index.js";
-import { isObjectNodeSchema } from "../node-kinds/index.js";
-import type { TreeSchema } from "./configuration.js";
+import { isArrayNodeSchema, isObjectNodeSchema } from "../node-kinds/index.js";
+import type { TreeSchema } from "../treeSchema.js";
 import type { IncrementalEncodingPolicy } from "../../feature-libraries/index.js";
 import { oneFromIterable } from "../../util/index.js";
 import { assert } from "@fluidframework/core-utils/internal";
 import type { FieldKey } from "../../core/index.js";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 /**
  * A symbol when present in the {@link AnnotatedAllowedTypes.metadata}'s `custom` property as true, opts in the allowed
@@ -68,7 +69,7 @@ function isIncrementalSummaryHintInAllowedTypes(allowedTypes: AllowedTypesFull):
 export function incrementalEncodingPolicyForAllowedTypes(
 	rootSchema: TreeSchema,
 ): IncrementalEncodingPolicy {
-	return (targetNodeIdentifier: string | undefined, targetFieldKey: string) => {
+	return (targetNodeIdentifier: string | undefined, targetFieldKey?: string) => {
 		if (targetNodeIdentifier === undefined) {
 			// Root fields cannot be allowed types, so we don't incrementally summarize them.
 			return false;
@@ -85,6 +86,11 @@ export function incrementalEncodingPolicyForAllowedTypes(
 		}
 
 		if (isObjectNodeSchema(targetNode)) {
+			if (targetFieldKey === undefined) {
+				throw new UsageError(
+					`Field key must be provided for object or array node '${targetNodeIdentifier}'`,
+				);
+			}
 			const targetPropertyKey = targetNode.storedKeyToPropertyKey.get(
 				targetFieldKey as FieldKey,
 			);
@@ -97,6 +103,12 @@ export function incrementalEncodingPolicyForAllowedTypes(
 			return false;
 		}
 
+		if (targetFieldKey !== undefined && !isArrayNodeSchema(targetNode)) {
+			throw new UsageError(
+				`Field key must not be provided for leaf, map or record node '${targetNodeIdentifier}'`,
+			);
+		}
+
 		const allowedTypes = oneFromIterable(
 			getTreeNodeSchemaPrivateData(targetNode).childAllowedTypes,
 		);

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

@@ -4,7 +4,6 @@
  */
 
 export type {
-	TreeSchema,
 	ITreeViewConfiguration,
 	ITreeConfigurationOptions,
 } from "./configuration.js";
@@ -29,6 +28,7 @@ export { asTreeViewAlpha } from "./tree.js";
 export { type SchemaStatics, schemaStatics } from "./schemaStatics.js";
 export {
 	SchemaFactory,
+	scoped,
 	type ScopedSchemaName,
 	type ObjectSchemaOptionsAlpha,
 	type ObjectSchemaOptions,
@@ -38,6 +38,10 @@ export {
 } from "./schemaFactory.js";
 export { SchemaFactoryBeta, type SchemaStaticsBeta } from "./schemaFactoryBeta.js";
 export { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
+export {
+	eraseSchemaDetails,
+	eraseSchemaDetailsSubclassable,
+} from "./eraseSchemaDetails.js";
 export type {
 	ValidateRecursiveSchema,
 	FixRecursiveArraySchema,
@@ -161,15 +165,14 @@ export {
 } from "./transactionTypes.js";
 
 export { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
-export { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 export type { TreeChangeEvents } from "./treeChangeEvents.js";
 export {
 	incrementalEncodingPolicyForAllowedTypes,
 	incrementalSummaryHint,
 } from "./incrementalAllowedTypes.js";
 export {
-	encodeSimpleSchema,
-	decodeSimpleSchema,
+	encodeSchemaCompatibilitySnapshot,
+	decodeSchemaCompatibilitySnapshot,
 } from "./simpleSchemaCodec.js";
 export {
 	exportCompatibilitySchemaSnapshot,

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

@@ -9,7 +9,7 @@ import { allowsRepoSuperset, defaultSchemaPolicy } from "../../feature-libraries
 import type { SchemaCompatibilityStatus } from "./tree.js";
 import { getDiscrepanciesInAllowedContent } from "./discrepancies.js";
 import { toUpgradeSchema } from "../toStoredSchema.js";
-import type { TreeSchema } from "./configuration.js";
+import type { TreeSchema } from "../treeSchema.js";
 
 /**
  * A collection of View information for schema

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

@@ -35,7 +35,7 @@ import type {
 	System_Unsafe,
 	TreeRecordNodeUnsafe,
 } from "./typesUnsafe.js";
-import type { SimpleObjectNodeSchema } from "../simpleSchema.js";
+import type { SchemaType, SimpleObjectNodeSchema } from "../simpleSchema.js";
 import { SchemaFactoryBeta } from "./schemaFactoryBeta.js";
 
 // These imports prevent a large number of type references in the API reports from showing up as *_2.
@@ -119,7 +119,7 @@ export class SchemaFactoryAlpha<
 		never,
 		TCustomMetadata
 	> &
-		SimpleObjectNodeSchema<TCustomMetadata> &
+		SimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> &
 		// We can't just use non generic `ObjectNodeSchema` here since "Base constructors must all have the same return type".
 		// We also can't just use generic `ObjectNodeSchema` here and not `TreeNodeSchemaClass` since that doesn't work with unsafe recursive types.
 		// ObjectNodeSchema<

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

@@ -182,7 +182,6 @@ export type ValidateRecursiveSchemaTemplate<T extends TreeNodeSchemaClass> =
 		}[T["kind"]]
 	>;
 
-/* eslint-disable @fluid-internal/fluid/no-hyphen-after-jsdoc-tag -- false positive AB#50920 */
 /**
  * Workaround for "Type instantiation is excessively deep and possibly infinite.ts" errors.
  * @remarks
@@ -240,7 +239,6 @@ export type ValidateRecursiveSchemaTemplate<T extends TreeNodeSchemaClass> =
  */
 export type FixRecursiveRecursionLimit<T extends TreeNodeSchemaClass> =
 	T extends ValidateRecursiveSchemaTemplate<T> ? undefined : undefined;
-/* eslint-enable @fluid-internal/fluid/no-hyphen-after-jsdoc-tag */
 
 /**
  * Does nothing with the provided value, but appears to use it to make unused locals warnings and errors go away.

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

@@ -18,13 +18,14 @@ import {
 	type FieldProps,
 } from "../fieldSchema.js";
 import type {
+	SchemaType,
 	SimpleAllowedTypeAttributes,
 	SimpleFieldSchema,
 	SimpleNodeSchema,
 	SimpleTreeSchema,
 } from "../simpleSchema.js";
 
-import type { TreeSchema } from "./configuration.js";
+import type { TreeSchema } from "../treeSchema.js";
 import { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
 
 const factory = new SchemaFactoryAlpha(undefined);
@@ -41,12 +42,17 @@ const factory = new SchemaFactoryAlpha(undefined);
  *
  * 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.
+ *
+ * @privateRemarks
+ * TODO: Add the ability for consumers to inject custom policy.
+ * For example, allow nodes with table schema identifiers to dispatch to `TableSchema` factory APIs.
+ *
  * @alpha
  */
 export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSchema {
 	const context: Context = new Map(
 		[...simple.definitions].map(
-			([id, schema]): [string, () => TreeNodeSchema & SimpleNodeSchema] => [
+			([id, schema]): [string, () => TreeNodeSchema & SimpleNodeSchema<SchemaType.View>] => [
 				id,
 				// This relies on the caching in evaluateLazySchema so that it only runs once.
 				() => generateNode(id, schema, context),
@@ -54,7 +60,7 @@ export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSc
 		),
 	);
 	const root = generateFieldSchema(simple.root, context, undefined);
-	const definitions = new Map<string, TreeNodeSchema & SimpleNodeSchema>();
+	const definitions = new Map<string, TreeNodeSchema & SimpleNodeSchema<SchemaType.View>>();
 	for (const [id, lazy] of context) {
 		definitions.set(id, lazy());
 	}
@@ -64,7 +70,7 @@ export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSc
 	};
 }
 
-type Context = ReadonlyMap<string, () => TreeNodeSchema & SimpleNodeSchema>;
+type Context = ReadonlyMap<string, () => TreeNodeSchema & SimpleNodeSchema<SchemaType.View>>;
 
 function generateFieldSchema(
 	simple: SimpleFieldSchema,
@@ -107,7 +113,7 @@ function generateNode(
 	id: string,
 	schema: SimpleNodeSchema,
 	context: Context,
-): TreeNodeSchema & SimpleNodeSchema {
+): TreeNodeSchema & SimpleNodeSchema<SchemaType.View> {
 	switch (schema.kind) {
 		case NodeKind.Object: {
 			const fields: Record<string, FieldSchema> = {};

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

@@ -30,15 +30,23 @@ import {
 } from "../../codec/index.js";
 
 /**
- * Encodes a simple schema (view or stored) into a serializable format.
+ * Encodes the compatibility impacting subset of simple schema (view or stored) into a serializable format.
+ *
  * @remarks The JSON-compatible schema returned from this method is only intended for use in snapshots/comparisons of schemas.
  * It is not possible to reconstruct a full schema (including metadata and persistedMetadata) from the encoded format.
  * @param treeSchema - The tree schema to convert.
  * @returns A serializable representation of the schema.
  *
+ * @privateRemarks
+ * Encodes to {@link Format.SimpleTreeSchemaFormat}.
+ *
+ * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.
+ *
  * @alpha
  */
-export function encodeSimpleSchema(simpleSchema: SimpleTreeSchema): JsonCompatibleReadOnly {
+export function encodeSchemaCompatibilitySnapshot(
+	simpleSchema: SimpleTreeSchema,
+): JsonCompatibleReadOnly {
 	// Convert types to serializable forms
 	const encodedDefinitions: Format.SimpleSchemaDefinitionsFormat = {};
 
@@ -63,9 +71,15 @@ export function encodeSimpleSchema(simpleSchema: SimpleTreeSchema): JsonCompatib
  * @returns A decoded simple schema.
  * @throws Will throw a usage error if the encoded schema is not in the expected format.
  *
+ * @privateRemarks
+ * If a validator is not provided, this implicitly performs an unsafe type conversion:
+ * this is something our user facing APIs generally avoid doing, and should be reconsidered before stabilizing.
+ *
+ * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.
+ *
  * @alpha
  */
-export function decodeSimpleSchema(
+export function decodeSchemaCompatibilitySnapshot(
 	encodedSchema: JsonCompatibleReadOnly,
 	validator?: FormatValidator,
 ): SimpleTreeSchema {

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

@@ -28,7 +28,7 @@ import type {
 	SimpleRecordNodeSchema,
 } from "../simpleSchema.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
-import type { TreeSchema } from "./configuration.js";
+import type { TreeSchema } from "../treeSchema.js";
 import type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
 import {
 	ArrayNodeSchema,

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

@@ -4,13 +4,16 @@
  */
 
 import type { JsonCompatibleReadOnly } from "../../util/index.js";
-import { toStoredSchema } from "../toStoredSchema.js";
+import { toInitialSchema } from "../toStoredSchema.js";
 import { TreeViewConfigurationAlpha, TreeViewConfiguration } from "./configuration.js";
+import { createTreeSchema } from "../treeSchema.js";
 import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
 import { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
-import { decodeSimpleSchema, encodeSimpleSchema } from "./simpleSchemaCodec.js";
+import {
+	decodeSchemaCompatibilitySnapshot,
+	encodeSchemaCompatibilitySnapshot,
+} from "./simpleSchemaCodec.js";
 import type { SchemaCompatibilityStatus } from "./tree.js";
-import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 
 /**
  * Compute the compatibility of using `view` to {@link ViewableTree.viewWith | view a tree} who's {@link ITreeAlpha.exportSimpleSchema | stored schema} could be derived from `viewWhichCreatedStoredSchema` via either {@link TreeView.initialize} or {@link TreeView.upgradeSchema}.
@@ -58,6 +61,9 @@ import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
  * @param view - The view being tested to see if it could view tree created or initialized using `viewWhichCreatedStoredSchema`.
  * @returns The compatibility status.
  *
+ * @privateRemarks
+ * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.
+ *
  * @alpha
  */
 export function checkCompatibility(
@@ -65,9 +71,7 @@ export function checkCompatibility(
 	view: TreeViewConfiguration,
 ): Omit<SchemaCompatibilityStatus, "canInitialize"> {
 	const viewAsAlpha = new TreeViewConfigurationAlpha({ schema: view.schema });
-	const stored = toStoredSchema(viewWhichCreatedStoredSchema.schema, {
-		includeStaged: () => true,
-	});
+	const stored = toInitialSchema(viewWhichCreatedStoredSchema.schema);
 	const tester = new SchemaCompatibilityTester(viewAsAlpha);
 	return tester.checkCompatibility(stored);
 }
@@ -95,13 +99,16 @@ export function checkCompatibility(
  * fs.writeFileSync("PointSchema.json", encodedSchema);
  * ```
  *
+ * @privateRemarks
+ * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.
+ *
  * @alpha
  */
 export function exportCompatibilitySchemaSnapshot(
 	config: Pick<TreeViewConfiguration, "schema">,
 ): JsonCompatibleReadOnly {
-	const simpleSchema = toSimpleTreeSchema(config.schema, true);
-	return encodeSimpleSchema(simpleSchema);
+	const treeSchema = createTreeSchema(config.schema);
+	return encodeSchemaCompatibilitySnapshot(treeSchema);
 }
 
 /**
@@ -120,13 +127,14 @@ export function exportCompatibilitySchemaSnapshot(
  * ```ts;
  * const oldViewSchema = importCompatibilitySchemaSnapshot(fs.readFileSync("PointSchema.json", "utf8"));
  * ```
- *
+ * @privateRemarks
+ * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.
  * @alpha
  */
 export function importCompatibilitySchemaSnapshot(
 	config: JsonCompatibleReadOnly,
 ): TreeViewConfiguration {
-	const simpleSchema = decodeSimpleSchema(config);
+	const simpleSchema = decodeSchemaCompatibilitySnapshot(config);
 	const viewSchema = generateSchemaFromSimpleSchema(simpleSchema);
 
 	// We construct a TreeViewConfiguration here with the default parameters. The default set of validation parameters are fine for