@fluidframework/tree 2.92.0 → 2.93.0

package/src/entrypoints/alpha.ts

@@ -102,10 +102,6 @@ export {
 	AnnotatedAllowedTypeUnsafe, 
 	AnnotatedAllowedTypes, 
 	AnnotatedAllowedTypesUnsafe, 
-	ArrayNodeDeltaOp, 
-	ArrayNodeInsertOp, 
-	ArrayNodeRemoveOp, 
-	ArrayNodeRetainOp, 
 	CodecWriteOptionsBeta, 
 	ConciseTree, 
 	ExtensibleUnionNode, 
@@ -116,13 +112,11 @@ export {
 	ForestTypeExpensiveDebug, 
 	ForestTypeOptimized, 
 	ForestTypeReference, 
+	IdentifierIndex, 
 	JsonCompatible, 
 	JsonCompatibleObject, 
 	KeyEncodingOptions, 
-	NodeChangedData,
-	NodeChangedDataAlpha,
-	NodeChangedDataDelta,
-	NodeChangedDataProperties,
+	NodeChangedData, 
 	ObjectSchemaOptions, 
 	PopUnion, 
 	RecordNodeInsertableData, 
@@ -136,9 +130,11 @@ export {
 	TableSchema, 
 	TreeBeta, 
 	TreeBranch, 
-	TreeChangeEventsBeta,
-	TreeChangeEventsAlpha,
+	TreeChangeEventsBeta, 
 	TreeEncodingOptions, 
+	TreeIndex, 
+	TreeIndexKey, 
+	TreeIndexNodes, 
 	TreeRecordNode, 
 	TreeRecordNodeUnsafe, 
 	TreeViewBeta, 
@@ -149,7 +145,9 @@ export {
 	adaptEnum, 
 	asBeta, 
 	configuredSharedTreeBeta, 
+	createIdentifierIndex, 
 	createIndependentTreeBeta, 
+	createTreeIndex, 
 	enumFromStrings, 
 	singletonSchema, 
 	snapshotSchemaCompatibility,
@@ -160,8 +158,14 @@ export {
 	ArrayNodeCustomizableSchema, 
 	ArrayNodeCustomizableSchemaAlpha, 
 	ArrayNodeCustomizableSchemaUnsafe, 
+	ArrayNodeDeltaOp, 
+	ArrayNodeInsertOp, 
 	ArrayNodePojoEmulationSchema, 
+	ArrayNodeRemoveOp, 
+	ArrayNodeRetainOp, 
 	ArrayNodeSchema, 
+	ArrayNodeTreeChangedDeltaOp, 
+	ArrayNodeTreeChangedRetainOp, 
 	ArrayPlaceAnchor, 
 	ChangeMetadata, 
 	CodecName, 
@@ -187,7 +191,6 @@ export {
 	HandleConverter, 
 	ICodecOptions, 
 	ITreeAlpha, 
-	IdentifierIndex, 
 	IncrementalEncodingPolicy, 
 	IndependentViewOptions, 
 	Insertable, 
@@ -220,6 +223,10 @@ export {
 	MapNodePojoEmulationSchema, 
 	MapNodeSchema, 
 	NoChangeConstraint, 
+	NodeChangedDataAlpha, 
+	NodeChangedDataDelta, 
+	NodeChangedDataProperties, 
+	NodeChangedDataTreeDelta, 
 	NodeProvider, 
 	NodeSchemaOptionsAlpha, 
 	ObjectNodeSchema, 
@@ -263,12 +270,11 @@ export {
 	TreeArrayNodeAlpha, 
 	TreeBranchAlpha, 
 	TreeBranchEvents, 
+	TreeChangeEventsAlpha, 
 	TreeCompressionStrategy, 
 	TreeContextAlpha, 
 	TreeIdentifierUtils, 
-	TreeIndex, 
-	TreeIndexKey, 
-	TreeIndexNodes, 
+	TreeMapNodeAlpha, 
 	TreeParsingOptions, 
 	TreeSchema, 
 	TreeSchemaEncodingOptions, 
@@ -290,9 +296,7 @@ export {
 	configuredSharedTreeAlpha, 
 	contentSchemaSymbol, 
 	createArrayInsertionAnchor, 
-	createIdentifierIndex, 
 	createIndependentTreeAlpha, 
-	createTreeIndex, 
 	decodeSchemaCompatibilitySnapshot, 
 	encodeSchemaCompatibilitySnapshot, 
 	eraseSchemaDetails, 

package/src/entrypoints/beta.ts

@@ -112,10 +112,11 @@ export {
 	ForestTypeExpensiveDebug, 
 	ForestTypeOptimized, 
 	ForestTypeReference, 
+	IdentifierIndex, 
 	JsonCompatible, 
 	JsonCompatibleObject, 
 	KeyEncodingOptions, 
-	NodeChangedData,
+	NodeChangedData, 
 	ObjectSchemaOptions, 
 	PopUnion, 
 	RecordNodeInsertableData, 
@@ -131,6 +132,9 @@ export {
 	TreeBranch, 
 	TreeChangeEventsBeta, 
 	TreeEncodingOptions, 
+	TreeIndex, 
+	TreeIndexKey, 
+	TreeIndexNodes, 
 	TreeRecordNode, 
 	TreeRecordNodeUnsafe, 
 	TreeViewBeta, 
@@ -141,7 +145,9 @@ export {
 	adaptEnum, 
 	asBeta, 
 	configuredSharedTreeBeta, 
+	createIdentifierIndex, 
 	createIndependentTreeBeta, 
+	createTreeIndex, 
 	enumFromStrings, 
 	singletonSchema, 
 	snapshotSchemaCompatibility

package/src/entrypoints/legacy.ts

@@ -102,10 +102,6 @@ export {
 	AnnotatedAllowedTypeUnsafe, 
 	AnnotatedAllowedTypes, 
 	AnnotatedAllowedTypesUnsafe, 
-	ArrayNodeDeltaOp, 
-	ArrayNodeInsertOp, 
-	ArrayNodeRemoveOp, 
-	ArrayNodeRetainOp, 
 	CodecWriteOptionsBeta, 
 	ConciseTree, 
 	ExtensibleUnionNode, 
@@ -116,13 +112,11 @@ export {
 	ForestTypeExpensiveDebug, 
 	ForestTypeOptimized, 
 	ForestTypeReference, 
+	IdentifierIndex, 
 	JsonCompatible, 
 	JsonCompatibleObject, 
 	KeyEncodingOptions, 
-	NodeChangedData,
-	NodeChangedDataAlpha,
-	NodeChangedDataDelta,
-	NodeChangedDataProperties,
+	NodeChangedData, 
 	ObjectSchemaOptions, 
 	PopUnion, 
 	RecordNodeInsertableData, 
@@ -136,9 +130,11 @@ export {
 	TableSchema, 
 	TreeBeta, 
 	TreeBranch, 
-	TreeChangeEventsBeta,
-	TreeChangeEventsAlpha,
+	TreeChangeEventsBeta, 
 	TreeEncodingOptions, 
+	TreeIndex, 
+	TreeIndexKey, 
+	TreeIndexNodes, 
 	TreeRecordNode, 
 	TreeRecordNodeUnsafe, 
 	TreeViewBeta, 
@@ -149,7 +145,9 @@ export {
 	adaptEnum, 
 	asBeta, 
 	configuredSharedTreeBeta, 
+	createIdentifierIndex, 
 	createIndependentTreeBeta, 
+	createTreeIndex, 
 	enumFromStrings, 
 	singletonSchema, 
 	snapshotSchemaCompatibility,

package/src/feature-libraries/chunked-forest/chunkTree.ts

@@ -424,8 +424,8 @@ export interface ChunkCompressor {
 	/**
 	 * If the idCompressor is provided, {@link UniformChunk}s with identifiers will be encoded for its in-memory representation.
 	 * @remarks
-	 * This compression applies to {@link UniformChunk}s when {@link TreeShape.maybeDecompressedStringAsNumber} is set.
-	 * If the `policy` does not use UniformChunks or does not set `maybeDecompressedStringAsNumber`, then no compression will be applied even when providing `idCompressor`.
+	 * This compression applies to {@link UniformChunk}s when {@link TreeShape.mayContainCompressedIds} is set.
+	 * If the `policy` does not use UniformChunks or does not set `mayContainCompressedIds`, then no compression will be applied even when providing `idCompressor`.
 	 */
 	readonly idCompressor: IIdCompressor | undefined;
 }
@@ -583,6 +583,7 @@ export function insertValues(
 	// Slow path: walk shape and cursor together, inserting values.
 	if (shape.hasValue) {
 		if (
+			shape.mayContainCompressedIds &&
 			typeof cursor.value === "string" &&
 			idCompressor !== undefined &&
 			isStableNodeIdentifier(cursor.value)

package/src/feature-libraries/chunked-forest/uniformChunk.ts

@@ -5,7 +5,6 @@
 
 import { assert, compareArrays, oob, fail } from "@fluidframework/core-utils/internal";
 import type { SessionSpaceCompressedId, IIdCompressor } from "@fluidframework/id-compressor";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	CursorLocationType,
@@ -54,7 +53,7 @@ export class UniformChunk extends ReferenceCountedBase implements TreeChunk {
 		idCompressor?: IIdCompressor,
 	) {
 		super();
-		this.idCompressor = idCompressor;
+		this.idCompressor = shape.treeShape.mayContainCompressedIds ? idCompressor : undefined;
 		assert(
 			shape.treeShape.valuesPerTopLevelNode * shape.topLevelLength === values.length,
 			0x4c3 /* invalid number of values for shape */,
@@ -100,30 +99,45 @@ export class TreeShape {
 	// TODO: this is only needed at chunk roots. Optimize it base on that.
 	public readonly positions: readonly NodePositionInfo[];
 
+	/**
+	 * Whether chunks using this shape (including any descendant leaf within it) may contain values compressed by the {@link UniformChunk.idCompressor}.
+	 *
+	 * @remarks
+	 * For string leaf nodes, this can be explicitly set to `true` to indicate that the value may be a compressed id
+	 * stored as a number that needs to be decompressed back to a string.
+	 * For non-leaf nodes, this is automatically derived from whether any child shapes have it set.
+	 */
+	public readonly mayContainCompressedIds: boolean;
+
 	/**
 	 *
 	 * @param type - {@link TreeNodeSchemaIdentifier} used to compare shapes.
 	 * @param hasValue - whether or not the TreeShape has a value.
 	 * @param fieldsArray - an array of {@link FieldShape} values, which contains a TreeShape for each FieldKey.
 	 *
-	 * @param maybeDecompressedStringAsNumber - used to check whether or not the value could have been compressed by the idCompressor.
-	 * This flag can only be set on string leaf nodes, and will throw a usage error otherwise.
-	 * If set to true, an additional check can be made (example: getting the value of {@link Cursor}) to return the original uncompressed value.
+	 * @param maybeCompressedIdLeaf - whether the value may have been compressed by the {@link UniformChunk.idCompressor}.
+	 * Can only be explicitly set to `true` on string leaf nodes; otherwise this constructor asserts.
+	 * For non-leaf nodes, {@link TreeShape.mayContainCompressedIds} is automatically derived from child shapes.
 	 */
 	public constructor(
 		public readonly type: TreeNodeSchemaIdentifier,
 		public readonly hasValue: boolean,
 		public readonly fieldsArray: readonly FieldShape[],
-		public readonly maybeDecompressedStringAsNumber: boolean = false,
+		maybeCompressedIdLeaf: boolean = false,
 	) {
-		if (
-			maybeDecompressedStringAsNumber &&
-			!(hasValue && type === "com.fluidframework.leaf.string")
-		) {
-			throw new UsageError(
-				"maybeDecompressedStringAsNumber flag can only be set to true for string leaf node.",
+		assert(
+			hasValue === false || fieldsArray.length === 0,
+			0xcef /* only non-leaf can have fields */,
+		);
+		if (maybeCompressedIdLeaf) {
+			assert(
+				hasValue && type === "com.fluidframework.leaf.string",
+				0xcf0 /* only strings can opt into maybeCompressedIdLeaf */,
 			);
 		}
+		// For non-leaf nodes, derive from whether any child shapes contain compressed ids.
+		this.mayContainCompressedIds =
+			maybeCompressedIdLeaf || fieldsArray.some(([, shape]) => shape.mayContainCompressedIds);
 		const fields: Map<FieldKey, OffsetShape> = new Map();
 		let numberOfValues = hasValue ? 1 : 0;
 		const infos: NodePositionInfo[] = [
@@ -146,7 +160,7 @@ export class TreeShape {
 	}
 
 	public equals(other: TreeShape): boolean {
-		// TODO: either dedup instances and/or store a collision resistant hash for fast compare.
+		// TODO: either dedupe instances and/or store a collision resistant hash for fast compare.
 
 		if (
 			!compareArrays(
@@ -157,7 +171,11 @@ export class TreeShape {
 		) {
 			return false;
 		}
-		return this.type === other.type && this.hasValue === other.hasValue;
+		return (
+			this.type === other.type &&
+			this.hasValue === other.hasValue &&
+			this.mayContainCompressedIds === other.mayContainCompressedIds
+		);
 	}
 
 	public withTopLevelLength(topLevelLength: number): ChunkShape {
@@ -548,16 +566,20 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 	}
 
 	public get value(): Value {
-		const idCompressor = this.chunk.idCompressor;
 		const info = this.nodeInfo(CursorLocationType.Nodes);
-		// If the maybeDecompressedStringAsNumber flag is set to true, we check if the value is a number.
-		// This flag can only ever be set on string leaf nodes, so if the value is a number, we can assume it is a compressible, known stable id.
-		if (info.shape.hasValue && info.shape.maybeDecompressedStringAsNumber) {
+		if (info.shape.hasValue) {
 			const value = this.chunk.values[info.valueOffset];
-			if (typeof value === "number" && idCompressor !== undefined) {
+			// If mayContainCompressedIds is set, check if the value is a number (i.e. a compressed ID that needs decompression).
+			if (info.shape.mayContainCompressedIds && typeof value === "number") {
+				const idCompressor = this.chunk.idCompressor;
+				assert(
+					idCompressor !== undefined,
+					0xcf1 /* chunk required idCompressor but did not provide it */,
+				);
 				return idCompressor.decompress(value as SessionSpaceCompressedId);
 			}
+			return value;
 		}
-		return info.shape.hasValue ? this.chunk.values[info.valueOffset] : undefined;
+		return undefined;
 	}
 }

package/src/feature-libraries/indexing/anchorTreeIndex.ts

@@ -51,6 +51,7 @@ export type KeyFinder<TKey> = (tree: ITreeSubscriptionCursor) => TKey;
  * calling {@link keys} will not include any keys that are stored in the index but only map to detached nodes.
  */
 export class AnchorTreeIndex<TKey, TValue> implements TreeIndex<TKey, TValue> {
+	public readonly [Symbol.toStringTag] = "AnchorTreeIndex";
 	public disposed = false;
 	/**
 	 * Caches {@link KeyFinder}s for each schema definition. If a schema maps to null, it does not

package/src/feature-libraries/indexing/types.ts

@@ -3,10 +3,12 @@
  * Licensed under the MIT License.
  */
 
+import type { FluidReadonlyMap } from "@fluidframework/core-interfaces/internal";
+
 /**
  * an array of nodes that is guaranteed to have at least one element
  *
- * @alpha
+ * @beta
  */
 export type TreeIndexNodes<TNode> = readonly [first: TNode, ...rest: TNode[]];
 
@@ -23,9 +25,9 @@ export type TreeIndexNodes<TNode> = readonly [first: TNode, ...rest: TNode[]];
  * Since currently partially loading a tree is not supported, there is no need for this.
  * At some point the low level shared tree index type for persisted indexes could be leveraged to provide user facing extensible sets of persisted indexes.
  * @sealed
- * @alpha
+ * @beta
  */
-export interface TreeIndex<TKey, TValue> extends ReadonlyMap<TKey, TValue> {
+export interface TreeIndex<TKey, TValue> extends FluidReadonlyMap<TKey, TValue> {
 	/**
 	 * Disposes the index such that it can no longer be used and receives no updates for changes in the tree.
 	 * @remarks

package/src/index.ts

@@ -111,6 +111,7 @@ export {
 	type TreeChangeEvents,
 	type NodeFromSchema,
 	type TreeMapNode,
+	type TreeMapNodeAlpha,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
 	type TreeLeafValue,
 	FieldKind,
@@ -136,10 +137,13 @@ export {
 	type ArrayNodeInsertOp,
 	type ArrayNodeRemoveOp,
 	type ArrayNodeRetainOp,
+	type ArrayNodeTreeChangedDeltaOp,
+	type ArrayNodeTreeChangedRetainOp,
 	type NodeChangedData,
 	type NodeChangedDataAlpha,
 	type NodeChangedDataDelta,
 	type NodeChangedDataProperties,
+	type NodeChangedDataTreeDelta,
 	type SchemaUpgrade,
 	contentSchemaSymbol,
 	// Types not really intended for public use, but used in links.

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.92.0";
+export const pkgVersion = "2.93.0";

package/src/serializableDomainSchema.ts

@@ -6,6 +6,12 @@
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 
 import {
+	// #region Unused imports to make d.ts cleaner
+	/* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars */
+	NodeKind,
+	System_Unsafe,
+	/* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars */
+	// #endregion
 	SchemaFactory,
 	SchemaFactoryBeta,
 	type FixRecursiveArraySchema,

package/src/shared-tree/treeAlpha.ts

@@ -240,8 +240,12 @@ export interface TreeAlpha {
 	 * @returns A callback function which will deregister the event.
 	 * This callback should be called only once.
 	 * @remarks
-	 * Provides a richer `nodeChanged` event than {@link (TreeBeta:interface).on} — for array nodes the
-	 * event data includes a {@link NodeChangedDataDelta.delta | delta} payload.
+	 * Provides richer events than {@link (TreeBeta:interface).on} for array nodes:
+	 * - `nodeChanged` includes a {@link NodeChangedDataDelta.delta | delta} payload for direct
+	 * changes (insert, remove, move).
+	 * - `treeChanged` also includes a {@link NodeChangedDataDelta.delta | delta} payload and fires
+	 * for both shallow changes and deep changes (e.g. a property of an element changed without
+	 * any direct array change).
 	 */
 	on<K extends keyof TreeChangeEventsAlpha<TNode>, TNode extends TreeNode>(
 		node: TNode,

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

@@ -363,7 +363,12 @@ function* getFieldDiscrepancies(
 		fail(0xbef /* A conversion from a FieldKind to a FlexFieldKind should exist */);
 
 	// This checks if the field kind in the view schema is not compatible with the stored schema.
-	if (viewKind.identifier !== stored.kind) {
+	// A staged optional field (optional in the view) is compatible with a required stored field
+	// during the rollout period — suppress the kind discrepancy in that case.
+	if (
+		viewKind.identifier !== stored.kind &&
+		!(view.isStagedOptional !== false && stored.kind === FieldKinds.required.identifier)
+	) {
 		yield {
 			identifier,
 			fieldKey,

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

@@ -17,7 +17,7 @@ import type { TreeView } from "./tree.js";
 /**
  * An index that returns tree nodes given their associated identifiers.
  *
- * @alpha
+ * @beta
  */
 export type IdentifierIndex = TreeIndex<string, TreeNode>;
 
@@ -28,7 +28,7 @@ function isStringKey(key: TreeIndexKey): key is string {
 /**
  * Creates an {@link IdentifierIndex} for a given {@link TreeView}.
  *
- * @alpha
+ * @beta
  */
 export function createIdentifierIndex<TSchema extends ImplicitFieldSchema>(
 	view: TreeView<TSchema>,

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

@@ -66,6 +66,7 @@ export {
 	createCustomizedFluidFrameworkScopedFactory,
 } from "./schemaCreationUtilities.js";
 export {
+	deltaMarksToArrayOps,
 	getIdentifierFromNode,
 	getPropertyKeyFromStoredKey,
 	getStoredKey,
@@ -158,9 +159,12 @@ export {
 	type ArrayNodeInsertOp,
 	type ArrayNodeRemoveOp,
 	type ArrayNodeRetainOp,
+	type ArrayNodeTreeChangedDeltaOp,
+	type ArrayNodeTreeChangedRetainOp,
 	type NodeChangedDataAlpha,
 	type NodeChangedDataDelta,
 	type NodeChangedDataProperties,
+	type NodeChangedDataTreeDelta,
 	type TreeChangeEventsAlpha,
 } from "./treeAlpha.js";
 export { createTreeIndex, type TreeIndexKey } from "./simpleTreeIndex.js";

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

@@ -11,6 +11,7 @@ import {
 	type WithType,
 	normalizeAllowedTypes,
 	isTreeNode,
+	createSchemaUpgrade,
 } from "../core/index.js";
 // These imports prevent a large number of type references in the API reports from showing up as *_2.
 /* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */
@@ -18,7 +19,7 @@ import {
 	type FieldProps,
 	type FieldSchemaAlpha,
 	type FieldPropsAlpha,
-	type FieldKind,
+	FieldKind,
 	type ImplicitFieldSchema,
 	type InsertableTreeFieldFromImplicitField,
 	type FieldSchema,
@@ -143,6 +144,42 @@ export interface SchemaStaticsAlpha {
 		TCustomMetadata,
 		FieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }
 	>;
+	/**
+	 * Creates a field schema that is Optional in the view but behaves as Required in the stored schema
+	 * during the rollout period of an optional-field migration.
+	 *
+	 * @remarks
+	 * Use this to incrementally migrate a required field to optional without a coordinated deployment.
+	 * The migration path is:
+	 *
+	 * 1. Start with `sf.required(T)` — all clients require the field.
+	 * 2. Deploy `sf.stagedOptional(T)` — new clients can read documents where the field is present or absent, but the stored schema stays Required (so old clients are unaffected). Writing `undefined` is blocked at runtime.
+	 * 3. Deploy `sf.optional(T)` once all clients support the staged optional field — the stored schema becomes Optional and the field can be cleared.
+	 *
+	 * Analogous to {@link SchemaStaticsBeta.staged} for allowed types, but for field optionality.
+	 *
+	 * @param t - The types allowed under the field.
+	 * @param props - Optional properties to associate with the field.
+	 *
+	 * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+	 * See {@link FieldSchemaMetadata.custom}.
+	 */
+	readonly stagedOptional: <
+		const T extends ImplicitAllowedTypes,
+		const TCustomMetadata = unknown,
+	>(
+		t: T,
+		props?: Omit<
+			FieldPropsAlpha<TCustomMetadata>,
+			"defaultProvider" | "stagedOptionalUpgrade"
+		>,
+	) => FieldSchemaAlpha<
+		FieldKind.Optional,
+		T,
+		TCustomMetadata,
+		FieldPropsAlpha<TCustomMetadata>
+	>;
+
 	/**
 	 * {@link SchemaStaticsAlpha.withDefault} except tweaked to work better for recursive types.
 	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
@@ -225,10 +262,28 @@ const withDefault = <
 	);
 };
 
+const stagedOptional = <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
+	t: T,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider" | "stagedOptionalUpgrade">,
+): FieldSchemaAlpha<
+	FieldKind.Optional,
+	T,
+	TCustomMetadata,
+	FieldPropsAlpha<TCustomMetadata>
+> => {
+	return createFieldSchema(FieldKind.Optional, t, {
+		defaultProvider: getDefaultProvider(() => []),
+		...props,
+		stagedOptionalUpgrade: createSchemaUpgrade(),
+	});
+};
+
 const schemaStaticsAlpha: SchemaStaticsAlpha = {
 	withDefault,
 
 	withDefaultRecursive: withDefault as SchemaStaticsAlpha["withDefaultRecursive"],
+
+	stagedOptional,
 };
 
 /**
@@ -448,7 +503,17 @@ export class SchemaFactoryAlpha<
 	public static readonly withDefaultRecursive = schemaStaticsAlpha.withDefaultRecursive;
 
 	/**
-	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
+	 * {@inheritdoc SchemaStaticsAlpha.stagedOptional}
+	 */
+	public readonly stagedOptional = schemaStaticsAlpha.stagedOptional;
+
+	/**
+	 * {@inheritdoc SchemaStaticsAlpha.stagedOptional}
+	 */
+	public static readonly stagedOptional = schemaStaticsAlpha.stagedOptional;
+
+	/**
+	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNodeAlpha}.
 	 *
 	 * @param name - Unique identifier for this schema within this factory's scope.
 	 * @param allowedTypes - The types that may appear as values in the map.

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

@@ -39,7 +39,7 @@ import { treeNodeApi } from "./treeNodeApi.js";
  * @remarks
  * This supports values which have value semantics and are compared by value, just like {@link TreeLeafValue}.
  * This allows using any tree value as a key (for example in an index tracking where those values occur in the tree).
- * @alpha
+ * @beta
  */
 export type TreeIndexKey = TreeLeafValue;
 
@@ -52,7 +52,7 @@ export type TreeIndexKey = TreeLeafValue;
  * @param getValue - given at least one {@link TreeNode}, returns an associated value
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
@@ -75,7 +75,7 @@ export function createTreeIndex<
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  * @param indexableSchema - a list of all the schema types that can be indexed
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
@@ -99,7 +99,7 @@ export function createTreeIndex<
  * @param getValue - given at least one {@link TreeNode}, returns an associated value
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
@@ -122,7 +122,7 @@ export function createTreeIndex<
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  * @param indexableSchema - a list of all the schema types that can be indexed
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
@@ -140,7 +140,7 @@ export function createTreeIndex<
 /**
  * Creates a {@link TreeIndex} with a specified indexer.
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,

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

@@ -53,7 +53,10 @@ export function extractPersistedSchema(
 	minVersionForCollab: MinimumVersionForCollab,
 	includeStaged: (upgrade: SchemaUpgrade) => boolean,
 ): JsonCompatible {
-	const stored = toStoredSchema(schema, { includeStaged });
+	const stored = toStoredSchema(schema, {
+		includeStaged,
+		includeStagedOptional: includeStaged,
+	});
 	const codec = schemaCodecBuilder.build({
 		minVersionForCollab,
 		jsonValidator: FormatValidatorNoOp,