@fluidframework/tree 2.72.0 → 2.74.0-365691

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

@@ -27,7 +27,7 @@ export {
 	type SummaryElementParser,
 	type SummaryElementStringifier,
 	type ClonableSchemaAndPolicy,
-	type SharedTreeCoreOptionsInternal as SharedTreCoreOptionsInternal,
+	type SharedTreeCoreOptionsInternal,
 } from "./sharedTreeCore.js";
 
 export type { ResubmitMachine } from "./resubmitMachine.js";
@@ -48,7 +48,7 @@ export {
 } from "./editManagerCodecs.js";
 export {
 	EditManagerFormatVersion,
-	editManagerFormatVersions,
+	supportedEditManagerFormatVersions,
 } from "./editManagerFormatCommons.js";
 export { EditManagerSummarizer } from "./editManagerSummarizer.js";
 export {
@@ -70,4 +70,8 @@ export {
 	clientVersionToMessageFormatVersion,
 	messageFormatVersionSelectorForSharedBranches,
 } from "./messageCodecs.js";
-export { MessageFormatVersion, messageFormatVersions } from "./messageFormat.js";
+export {
+	MessageFormatVersion,
+	messageFormatVersions,
+	supportedMessageFormatVersions,
+} from "./messageFormat.js";

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

@@ -5,6 +5,11 @@
 
 import { unreachableCase } from "@fluidframework/core-utils/internal";
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+import {
+	getConfigForMinVersionForCollab,
+	lowestMinVersionForCollab,
+} from "@fluidframework/runtime-utils/internal";
+
 import {
 	type CodecTree,
 	type CodecWriteOptions,
@@ -15,6 +20,7 @@ import {
 	type ICodecOptions,
 	type IJsonCodec,
 	makeCodecFamily,
+	makeDiscontinuedCodecVersion,
 	makeVersionDispatchingCodec,
 } from "../codec/index.js";
 import type {
@@ -45,10 +51,12 @@ export function clientVersionToMessageFormatVersion(
 	clientVersion: MinimumVersionForCollab,
 	writeVersionOverride?: MessageFormatVersion,
 ): MessageFormatVersion {
-	const compatibleVersion: MessageFormatVersion =
-		clientVersion < FluidClientVersion.v2_43
-			? brand(MessageFormatVersion.v3)
-			: brand(MessageFormatVersion.v4);
+	const compatibleVersion: MessageFormatVersion = brand(
+		getConfigForMinVersionForCollab(clientVersion, {
+			[lowestMinVersionForCollab]: MessageFormatVersion.v3,
+			[FluidClientVersion.v2_43]: MessageFormatVersion.v4,
+		}),
+	);
 	return writeVersionOverride ?? compatibleVersion;
 }
 
@@ -123,29 +131,36 @@ export function makeMessageCodecs<TChangeset>(
 			MessageEncodingContext
 		>,
 	][] = Array.from(messageFormatVersions).map((version) => {
-		const changeCodec = changeCodecs.resolve(
-			dependentChangeFormatVersion.lookup(version),
-		).json;
 		switch (version) {
 			case MessageFormatVersion.undefined:
 			case MessageFormatVersion.v1:
-			case MessageFormatVersion.v2:
+			case MessageFormatVersion.v2: {
+				const versionOrUndefined =
+					version === MessageFormatVersion.undefined ? undefined : version;
+				return [
+					versionOrUndefined,
+					makeDiscontinuedCodecVersion(options, versionOrUndefined, "2.73.0"),
+				];
+			}
 			case MessageFormatVersion.v3:
-			case MessageFormatVersion.v4:
+			case MessageFormatVersion.v4: {
+				const changeCodec = changeCodecs.resolve(
+					dependentChangeFormatVersion.lookup(version),
+				).json;
 				return [
-					version === MessageFormatVersion.undefined ? undefined : version,
-					makeV1ToV4CodecWithVersion(
-						changeCodec,
-						revisionTagCodec,
-						options,
-						version === MessageFormatVersion.undefined ? MessageFormatVersion.v1 : version,
-					),
+					version,
+					makeV1ToV4CodecWithVersion(changeCodec, revisionTagCodec, options, version),
 				];
-			case MessageFormatVersion.v5:
+			}
+			case MessageFormatVersion.v5: {
+				const changeCodec = changeCodecs.resolve(
+					dependentChangeFormatVersion.lookup(version),
+				).json;
 				return [
 					version,
 					makeV5CodecWithVersion(changeCodec, revisionTagCodec, options, version),
 				];
+			}
 			default:
 				unreachableCase(version);
 		}

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

@@ -12,20 +12,17 @@ export const MessageFormatVersion = {
 	/**
 	 * NOTE: this is written as `undefined` rather than `0` in the wire format.
 	 * Introduced and retired prior to 2.0.
-	 * Reading capability is currently maintained for backwards compatibility, but it could be removed in the future.
-	 * Writing capability need not be maintained.
+	 * Reading and writing capability removed in 2.73.0.
 	 */
 	undefined: 0,
 	/**
 	 * Introduced and retired prior to 2.0.
-	 * Reading capability is currently maintained for backwards compatibility, but it could be removed in the future.
-	 * Writing capability need not be maintained.
+	 * Reading and writing capability removed in 2.73.0.
 	 */
 	v1: 1,
 	/**
 	 * Introduced and retired prior to 2.0.
-	 * Reading capability is currently maintained for backwards compatibility, but it could be removed in the future.
-	 * Writing capability need not be maintained.
+	 * Reading and writing capability removed in 2.73.0.
 	 */
 	v2: 2,
 	/**
@@ -51,6 +48,11 @@ export type MessageFormatVersion = Brand<
 	(typeof MessageFormatVersion)[keyof typeof MessageFormatVersion],
 	"MessageFormatVersion"
 >;
+export const supportedMessageFormatVersions: ReadonlySet<MessageFormatVersion> = new Set([
+	MessageFormatVersion.v3,
+	MessageFormatVersion.v4,
+	MessageFormatVersion.v5,
+] as MessageFormatVersion[]);
 export const messageFormatVersions: ReadonlySet<MessageFormatVersion> = new Set(
 	Object.values(MessageFormatVersion) as MessageFormatVersion[],
 );

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

@@ -175,22 +175,22 @@ export class TreeViewConfiguration<
 	/**
 	 * {@inheritDoc ITreeViewConfiguration.schema}
 	 */
-	public readonly schema: TSchema;
+	public readonly schema!: TSchema;
 
 	/**
 	 * {@inheritDoc ITreeConfigurationOptions.enableSchemaValidation}
 	 */
-	public readonly enableSchemaValidation: boolean;
+	public readonly enableSchemaValidation!: boolean;
 
 	/**
 	 * {@inheritDoc ITreeConfigurationOptions.preventAmbiguity}
 	 */
-	public readonly preventAmbiguity: boolean;
+	public readonly preventAmbiguity!: boolean;
 
 	/**
 	 * {@link TreeSchema.definitions} but with public types.
 	 */
-	protected readonly definitionsInternal: ReadonlyMap<string, TreeNodeSchema>;
+	protected readonly definitionsInternal!: ReadonlyMap<string, TreeNodeSchema>;
 
 	/**
 	 * Construct a new {@link TreeViewConfiguration}.
@@ -206,6 +206,17 @@ export class TreeViewConfiguration<
 	 * since this would be a cyclic dependency that will cause an error when constructing this configuration.
 	 */
 	public constructor(props: ITreeViewConfiguration<TSchema>) {
+		if (this.constructor === TreeViewConfiguration) {
+			// Ensure all TreeViewConfiguration instances are actually TreeViewConfigurationAlpha, allowing `asAlpha` to work correctly.
+			// If everything in TreeViewConfigurationAlpha is stabilized and this is removed, the `!` on the properties above should be removed to restore better type safety.
+			return new TreeViewConfigurationAlpha(props);
+		}
+		assert(
+			// The type cast here is needed to avoid this assert narrowing "this" to never, breaking the code below.
+			(this.constructor as unknown) === TreeViewConfigurationAlpha,
+			0xc9e /* Invalid configuration class constructed. */,
+		);
+
 		const config = { ...defaultTreeConfigurationOptions, ...props };
 		this.schema = config.schema;
 		this.enableSchemaValidation = config.enableSchemaValidation;
@@ -252,6 +263,8 @@ export class TreeViewConfiguration<
 
 /**
  * {@link TreeViewConfiguration} extended with some alpha APIs.
+ * @remarks
+ * See {@link (asAlpha:2)} for an API to downcast from {@link TreeViewConfiguration} to this type.
  * @sealed @alpha
  */
 export class TreeViewConfigurationAlpha<

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

@@ -3,21 +3,21 @@
  * Licensed under the MIT License.
  */
 
-import type { FieldKey, TreeNodeSchemaIdentifier } from "../../core/index.js";
 import { getTreeNodeSchemaPrivateData, type AllowedTypesFull } from "../core/index.js";
 import { isObjectNodeSchema } from "../node-kinds/index.js";
 import type { TreeSchema } from "./configuration.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";
 
 /**
- * A symbol when present in the {@link AnnotatedAllowedTypes.metadata.custom} property as true, opts in the allowed
+ * A symbol when present in the {@link AnnotatedAllowedTypes.metadata}'s `custom` property as true, opts in the allowed
  * types to incremental summary optimization.
  * These allowed types will be optimized during summary such that if they don't change across summaries,
  * they will not be encoded and their content will not be included in the summary that is uploaded to the service.
  * @remarks
- * See {@link getShouldIncrementallySummarizeAllowedTypes} for more details.
+ * See {@link incrementalEncodingPolicyForAllowedTypes} for more details.
  *
  * Use {@link SchemaStaticsBeta.types} to add this metadata to allowed types in a schema.
  * @example
@@ -29,6 +29,7 @@ import { assert } from "@fluidframework/core-utils/internal";
  *   }),
  * }) {}
  * ```
+ * @alpha
  */
 export const incrementalSummaryHint: unique symbol = Symbol("IncrementalSummaryHint");
 
@@ -44,31 +45,30 @@ function isIncrementalSummaryHintInAllowedTypes(allowedTypes: AllowedTypesFull):
 }
 
 /**
- * This helper function {@link getShouldIncrementallySummarizeAllowedTypes} can be used to generate a callback function
- * of type {@link IncrementalEncodingPolicy}.
- * This callback can be passed as the value for {@link SharedTreeOptionsInternal.shouldEncodeFieldIncrementally} parameter
+ * This helper function {@link incrementalEncodingPolicyForAllowedTypes} can be used to generate a callback function
+ * of type {@link IncrementalEncodingPolicy}. It determines if each {@link AllowedTypes} in a schema should be
+ * incrementally summarized.
+ * This callback can be passed as the value for {@link SharedTreeOptions.shouldEncodeIncrementally} parameter
  * when creating the tree.
- * It will be called for each {@link AllowedTypes} in the schema to determine if it should be incrementally summarized.
  *
  * @param rootSchema - The schema for the root of the tree.
- * @returns A callback function of type {@link IncrementalEncodingPolicy} which can be used to determine if a field
- * should be incrementally summarized based on whether it is an allowed types with the
- * {@link incrementalAllowedTypesMetadata} metadata.
+ * @returns A callback function of type {@link IncrementalEncodingPolicy} which determines if allowed types should
+ * be incrementally summarized based on whether they have opted in via the {@link incrementalSummaryHint} metadata.
  *
  * @remarks
  * This only works for forest type {@link ForestTypeOptimized} and compression strategy
- * {@link TreeCompressionStrategyExtended.CompressedIncremental}.
+ * {@link TreeCompressionStrategy.CompressedIncremental}.
  *
- * The {@link incrementalAllowedTypesMetadata} will be replaced with a specialized metadata property once the
+ * @privateRemarks
+ * The {@link incrementalSummaryHint} will be replaced with a specialized metadata property once the
  * incremental summary feature and APIs are stabilized.
+ *
+ * @alpha
  */
-export function getShouldIncrementallySummarizeAllowedTypes(
+export function incrementalEncodingPolicyForAllowedTypes(
 	rootSchema: TreeSchema,
 ): IncrementalEncodingPolicy {
-	return (
-		targetNodeIdentifier: TreeNodeSchemaIdentifier | undefined,
-		targetFieldKey: FieldKey,
-	) => {
+	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,7 +85,9 @@ export function getShouldIncrementallySummarizeAllowedTypes(
 		}
 
 		if (isObjectNodeSchema(targetNode)) {
-			const targetPropertyKey = targetNode.storedKeyToPropertyKey.get(targetFieldKey);
+			const targetPropertyKey = targetNode.storedKeyToPropertyKey.get(
+				targetFieldKey as FieldKey,
+			);
 			if (targetPropertyKey !== undefined) {
 				const fieldSchema = targetNode.fields.get(targetPropertyKey);
 				if (fieldSchema !== undefined) {

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

@@ -164,10 +164,15 @@ export { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
 export { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 export type { TreeChangeEvents } from "./treeChangeEvents.js";
 export {
-	getShouldIncrementallySummarizeAllowedTypes,
+	incrementalEncodingPolicyForAllowedTypes,
 	incrementalSummaryHint,
 } from "./incrementalAllowedTypes.js";
 export {
 	encodeSimpleSchema,
 	decodeSimpleSchema,
 } from "./simpleSchemaCodec.js";
+export {
+	exportCompatibilitySchemaSnapshot,
+	importCompatibilitySchemaSnapshot,
+	checkCompatibility,
+} from "./snapshotCompatibilityChecker.js";

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

@@ -5,7 +5,12 @@
 
 import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
 
-import { NodeKind, type TreeNodeSchema, type AllowedTypes } from "../core/index.js";
+import {
+	NodeKind,
+	type TreeNodeSchema,
+	type AllowedTypesFull,
+	SchemaUpgrade,
+} from "../core/index.js";
 import {
 	type FieldSchema,
 	type FieldSchemaAlpha,
@@ -88,11 +93,14 @@ function generateFieldSchema(
 function generateAllowedTypes(
 	allowed: ReadonlyMap<string, SimpleAllowedTypeAttributes>,
 	context: Context,
-): AllowedTypes {
-	return Array.from(
-		allowed.keys(),
-		(id) => context.get(id) ?? fail(0xb5a /* Missing schema */),
-	);
+): AllowedTypesFull {
+	const types = Array.from(allowed.entries(), ([id, attributes]) => {
+		const schema = context.get(id) ?? fail(0xb5a /* Missing schema */);
+		return attributes.isStaged instanceof SchemaUpgrade ? factory.staged(schema) : schema;
+	});
+	// TODO: AB#53315: `AllowedTypesFullFromMixed` does not correctly handle the `(AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]` case.
+	// We have to cast here in order to produce an allowed types list that can be used in tree node factory methods (e.g., `SchemaFactoryAlpha.objectAlpha`).
+	return SchemaFactoryAlpha.types(types) as AllowedTypesFull;
 }
 
 function generateNode(

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

@@ -17,7 +17,7 @@ import type {
 	SimpleRecordNodeSchema,
 	SimpleTreeSchema,
 } from "../simpleSchema.js";
-import { NodeKind } from "../core/index.js";
+import { createSchemaUpgrade, NodeKind, SchemaUpgrade } from "../core/index.js";
 import type { FieldKind } from "../fieldSchema.js";
 import type { ValueSchema } from "../../core/index.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
@@ -153,9 +153,8 @@ function encodeSimpleAllowedTypes(
 ): Format.SimpleAllowedTypesFormat {
 	const encodedAllowedTypes: Format.SimpleAllowedTypesFormat = {};
 	for (const [identifier, attributes] of simpleAllowedTypes) {
-		encodedAllowedTypes[identifier] = {
-			isStaged: attributes.isStaged,
-		};
+		const isStaged = attributes.isStaged instanceof SchemaUpgrade ? true : attributes.isStaged;
+		encodedAllowedTypes[identifier] = { isStaged };
 	}
 	return encodedAllowedTypes;
 }
@@ -350,11 +349,13 @@ function decodeSimpleAllowedTypes(
 ): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
 	const untypedMap = objectToMap(encodedAllowedTypes);
 
-	const simpleAllowedTypes = transformMapValues(untypedMap, (value) => {
-		return {
-			isStaged: value.isStaged,
-		} satisfies SimpleAllowedTypeAttributes;
-	});
+	const simpleAllowedTypes = transformMapValues(
+		untypedMap,
+		(value): SimpleAllowedTypeAttributes => {
+			const isStaged = value.isStaged === true ? createSchemaUpgrade() : value.isStaged;
+			return { isStaged };
+		},
+	);
 
 	return simpleAllowedTypes;
 }

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

@@ -0,0 +1,135 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { JsonCompatibleReadOnly } from "../../util/index.js";
+import { toStoredSchema } from "../toStoredSchema.js";
+import { TreeViewConfigurationAlpha, TreeViewConfiguration } from "./configuration.js";
+import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
+import { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
+import { decodeSimpleSchema, encodeSimpleSchema } 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}.
+ *
+ * @remarks See {@link SchemaCompatibilityStatus} for details on the compatibility results.
+ *
+ * @example This example demonstrates checking the compatibility of a historical schema against a current schema.
+ * In this case, the historical schema is a Point2D object with x and y fields, while the current schema is a Point3D object
+ * that adds an optional z field.
+ *
+ * ```ts
+ * // This snapshot is assumed to be the same as Point3D, except missing `z`.
+ * const encodedSchema = JSON.parse(fs.readFileSync("PointSchema.json", "utf8"));
+ * const oldViewSchema = importCompatibilitySchemaSnapshot(encodedSchema);
+ *
+ * // Build the current view schema
+ * class Point3D extends factory.object("Point", {
+ * 	x: factory.number,
+ * 	y: factory.number,
+ *
+ * 	// The current schema has a new optional field that was not present on Point2D
+ * 	z: factory.optional(factory.number),
+ * }) {}
+ * const currentViewSchema = new TreeViewConfiguration({ schema: Point3D });
+ *
+ * // Check to see if the document created by the historical view schema can be opened with the current view schema
+ * const backwardsCompatibilityStatus = checkCompatibility(oldViewSchema, currentViewSchema);
+ *
+ * // z is not present in Point2D, so the schema must be upgraded
+ * assert.equal(backwardsCompatibilityStatus.canView, false);
+ *
+ * // The schema can be upgraded to add the new optional field
+ * assert.equal(backwardsCompatibilityStatus.canUpgrade, true);
+ *
+ * // Test what the old version of the application would do with a tree using the new schema:
+ * const forwardsCompatibilityStatus = checkCompatibility(currentViewSchema, oldViewSchema);
+ *
+ * // If the old schema set allowUnknownOptionalFields, this would be true, but since it did not,
+ * // this assert will fail, detecting the forwards compatibility break:
+ * // this means these two versions of the application cannot collaborate on content using these schema.
+ * assert.equal(forwardsCompatibilityStatus.canView, true);
+ * ```
+ *
+ * @param viewWhichCreatedStoredSchema - From which to derive the stored schema, as if it initialized or upgraded a tree via {@link TreeView}.
+ * @param view - The view being tested to see if it could view tree created or initialized using `viewWhichCreatedStoredSchema`.
+ * @returns The compatibility status.
+ *
+ * @alpha
+ */
+export function checkCompatibility(
+	viewWhichCreatedStoredSchema: TreeViewConfiguration,
+	view: TreeViewConfiguration,
+): Omit<SchemaCompatibilityStatus, "canInitialize"> {
+	const viewAsAlpha = new TreeViewConfigurationAlpha({ schema: view.schema });
+	const stored = toStoredSchema(viewWhichCreatedStoredSchema.schema, {
+		includeStaged: () => true,
+	});
+	const tester = new SchemaCompatibilityTester(viewAsAlpha);
+	return tester.checkCompatibility(stored);
+}
+
+/**
+ * Returns a JSON compatible representation of the tree schema for snapshot compatibility checking.
+ *
+ * Snapshots can be loaded by the same or newer package versions, but not necessarily older versions.
+ *
+ * @see {@link importCompatibilitySchemaSnapshot} which loads these snapshots.
+ *
+ * @param config - The schema to snapshot. Only the schema field of the `TreeViewConfiguration` is used.
+ * @returns The JSON representation of the schema.
+ *
+ * @example This example creates and persists a snapshot of a Point2D schema.
+ *
+ * ```ts
+ * const schemaFactory = new SchemaFactory("test");
+ * class Point2D extends schemaFactory.object("Point", {
+ * 	x: factory.number,
+ * 	y: factory.number,
+ * }) {}
+ * const viewSchema = new TreeViewConfiguration({ schema: Point2D });
+ * const encodedSchema = JSON.stringify(exportCompatibilitySchemaSnapshot(viewSchema));
+ * fs.writeFileSync("PointSchema.json", encodedSchema);
+ * ```
+ *
+ * @alpha
+ */
+export function exportCompatibilitySchemaSnapshot(
+	config: Pick<TreeViewConfiguration, "schema">,
+): JsonCompatibleReadOnly {
+	const simpleSchema = toSimpleTreeSchema(config.schema, true);
+	return encodeSimpleSchema(simpleSchema);
+}
+
+/**
+ * Parse the format exported by {@link exportCompatibilitySchemaSnapshot} into a schema.
+ *
+ * Can load snapshots created by the same or older package versions, but not necessarily newer versions.
+ *
+ * @see {@link exportCompatibilitySchemaSnapshot} which creates these snapshots.
+ *
+ * @param config - The JSON representation of the schema.
+ * @returns The schema. Only the schema field of the {@link TreeViewConfiguration} is populated.
+ * @throws Will throw a usage error if the encoded schema is not in the expected format.
+ *
+ * @example This example loads and parses a snapshot of a Point2D schema.
+ *
+ * ```ts;
+ * const oldViewSchema = importCompatibilitySchemaSnapshot(fs.readFileSync("PointSchema.json", "utf8"));
+ * ```
+ *
+ * @alpha
+ */
+export function importCompatibilitySchemaSnapshot(
+	config: JsonCompatibleReadOnly,
+): TreeViewConfiguration {
+	const simpleSchema = decodeSimpleSchema(config);
+	const viewSchema = generateSchemaFromSimpleSchema(simpleSchema);
+
+	// We construct a TreeViewConfiguration here with the default parameters. The default set of validation parameters are fine for
+	// a schema produced by `generateSchemaFromSimpleSchema`.
+	return new TreeViewConfiguration({ schema: viewSchema.root });
+}

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

@@ -449,7 +449,7 @@ export interface SchemaCompatibilityStatus {
 	 *
 	 * In these cases `canUpgrade` and `isEquivalent` will be false.
 	 *
-	 * When the documents allowed by the view schema is a strict superset of those by the stored schema,
+	 * When the set of documents allowed by the view schema is a strict superset of those allowed by the stored schema,
 	 * `canView` is false because writes to the document using the view schema could make the document violate its stored schema.
 	 * In this case, the stored schema could be updated to match the provided view schema, allowing read-write access to the tree.
 	 * See {@link SchemaCompatibilityStatus.canUpgrade}.
@@ -577,7 +577,7 @@ export interface TreeViewEvents {
 /**
  * Retrieve the {@link TreeViewAlpha | alpha API} for a {@link TreeView}.
  * @alpha
- * @deprecated Use {@link asAlpha} instead.
+ * @deprecated Use {@link (asAlpha:1)} instead.
  * @privateRemarks Despite being deprecated, this function should be used within the tree package (outside of tests) rather than `asAlpha` in order to avoid circular import dependencies.
  */
 export function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(

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

@@ -262,7 +262,7 @@ export class AnnotatedAllowedTypesInternal<
 		const simpleAllowedTypes = new Map<string, SimpleAllowedTypeAttributes>();
 		for (const type of annotatedAllowedTypes.evaluate().types) {
 			simpleAllowedTypes.set(type.type.identifier, {
-				isStaged: type.metadata.stagedSchemaUpgrade !== undefined,
+				isStaged: type.metadata.stagedSchemaUpgrade ?? false,
 			});
 		}
 		return simpleAllowedTypes;

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

@@ -65,6 +65,7 @@ export {
 	createSchemaUpgrade,
 	AnnotatedAllowedTypesInternal,
 	normalizeAllowedTypesInternal,
+	SchemaUpgrade,
 } from "./allowedTypes.js";
 export type {
 	AnnotatedAllowedType,
@@ -80,7 +81,6 @@ export type {
 	AllowedTypeMetadata,
 	AnnotatedAllowedTypes,
 	AnnotateAllowedTypesList,
-	SchemaUpgrade,
 	AllowedTypesFullInternal,
 	AllowedTypesFull,
 	AllowedTypesFullFromMixed,
@@ -117,4 +117,6 @@ export {
 	type StoredSchemaGenerationOptions,
 	convertAllowedTypes,
 	allowedTypeFilter,
+	type StoredFromViewSchemaGenerationOptions,
+	ExpectStored,
 } from "./toStored.js";