@fluidframework/tree 2.92.0 → 2.100.0

package/src/feature-libraries/forest-summary/incrementalSummaryBuilder.ts

@@ -50,10 +50,12 @@ interface ChunkLoadProperties {
 	 */
 	readonly encodedContents: EncodedFieldBatchV2;
 	/**
-	 * The path for this chunk's contents in the summary tree relative to the forest's summary tree.
-	 * This path is used to generate a summary handle for the chunk if it doesn't change between summaries.
+	 * The reference ID of this chunk's parent in the summary tree, or `undefined` if this chunk is
+	 * at the top level (directly under the forest summary tree).
+	 * Stored here so that {@link ForestIncrementalSummaryBuilder.decodeIncrementalChunk} can
+	 * reconstruct the correct {@link ChunkSummaryProperties} without re-parsing a path string.
 	 */
-	readonly summaryPath: string;
+	readonly parentReferenceId: ChunkReferenceId | undefined;
 }
 
 /**
@@ -68,10 +70,20 @@ interface ChunkSummaryProperties {
 	 */
 	readonly referenceId: ChunkReferenceId;
 	/**
-	 * The path for this chunk's summary in the summary tree relative to the forest's summary tree.
-	 * This path is used to generate a summary handle for the chunk if it doesn't change between summaries.
+	 * The reference ID of this chunk's parent in the summary tree, or `undefined` if this chunk
+	 * is at the top level (has no incremental parent).
+	 *
+	 * @remarks
+	 * Storing only the immediate parent (rather than the full path string) keeps every chunk's
+	 * tracking entry correct even when an ancestor is re-encoded and receives a new reference ID.
+	 * The full summary path is computed on demand by {@link ForestIncrementalSummaryBuilder.computeHandlePathInLatestSummary}
+	 * by walking up the parent chain through {@link TrackedSummaryProperties.latestSummaryRefIdMap}.
+	 *
+	 * If a parent chunk is encoded as a handle in the current summary its reference ID is unchanged,
+	 * so its children's `parentReferenceId` values copied forward by `completeSummary` remain valid
+	 * without any additional update.
 	 */
-	readonly summaryPath: string;
+	readonly parentReferenceId: ChunkReferenceId | undefined;
 }
 
 /**
@@ -109,6 +121,13 @@ interface TrackedSummaryProperties {
 	 * Serializes content (including {@link (IFluidHandle:interface)}s) for adding to a summary blob.
 	 */
 	stringify: SummaryElementStringifier;
+	/**
+	 * Reverse lookup map for the latest summary: maps each chunk's {@link ChunkReferenceId} to its
+	 * {@link ChunkSummaryProperties}.
+	 * Used by {@link ForestIncrementalSummaryBuilder.computeHandlePathInLatestSummary} to traverse
+	 * the parent chain when generating handle paths.
+	 */
+	readonly latestSummaryRefIdMap: Map<ChunkReferenceId, ChunkSummaryProperties>;
 }
 
 /**
@@ -177,6 +196,16 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 	/**
 	 * For a given summary sequence number, keeps track of a chunk's properties that will be used to generate
 	 * a summary handle for the chunk if it does not change between summaries.
+	 *
+	 * @remarks
+	 * `chunk` (the TreeChunk object) is used as the map key by object identity.
+	 * This assumes each chunk appears at exactly one position in the forest — an invariant that holds because every
+	 * node in a tree has a single parent.
+	 * If the forest ever introduced structural sharing (two positions backed by the same TreeChunk object),
+	 * a second call here would silently overwrite the first entry, causing the first position's handle to point
+	 * to the second position's parent in subsequent summaries. In theory, this should be fine from summary perspective
+	 * because the chunk contents are the same. But, it could lead to confusing handle paths in the summary tree and
+	 * may lead to other unexpected behavior. Adequate tests should be added if structural sharing is introduced.
 	 */
 	private readonly chunkTrackingPropertiesMap: NestedMap<
 		number,
@@ -249,12 +278,14 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		// the contents of incremental chunks in any sub-trees.
 		const downloadChunkContentsInTree = async (
 			snapshotTree: ISnapshotTree,
-			parentTreeKey: string,
+			parentPathSegments: string[],
+			parentReferenceId: ChunkReferenceId | undefined,
 		): Promise<void> => {
 			// All trees in the snapshot tree are for incremental chunks. The key is the chunk's reference ID
 			// and the value is the snapshot tree for the chunk.
 			for (const [chunkReferenceId, chunkSnapshotTree] of Object.entries(snapshotTree.trees)) {
-				const chunkSubTreePath = `${parentTreeKey}${chunkReferenceId}`;
+				const chunkSubTreeSegments = [...parentPathSegments, chunkReferenceId];
+				const chunkSubTreePath = chunkSubTreeSegments.join("/");
 				const chunkContentsPath = `${chunkSubTreePath}/${summaryContentBlobKey}`;
 				if (!(await args.services.contains(chunkContentsPath))) {
 					throw new LoggingError(
@@ -266,7 +297,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				)) as EncodedFieldBatchV2; // TODO: this should use a codec to validate the data instead of just type casting.
 				this.loadedChunksMap.set(chunkReferenceId, {
 					encodedContents: chunkContents,
-					summaryPath: chunkSubTreePath,
+					parentReferenceId,
 				});
 
 				const chunkReferenceIdNumber = Number(chunkReferenceId);
@@ -275,10 +306,15 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				);
 
 				// Recursively download the contents of chunks in this chunk's sub tree.
-				await downloadChunkContentsInTree(chunkSnapshotTree, `${chunkSubTreePath}/`);
+				await downloadChunkContentsInTree(
+					chunkSnapshotTree,
+					chunkSubTreeSegments,
+					brand(chunkReferenceIdNumber),
+				);
 			}
 		};
-		await downloadChunkContentsInTree(forestTree, "");
+		// parentReferenceId is undefined for the root of the forest tree.
+		await downloadChunkContentsInTree(forestTree, [], undefined /* parentReferenceId */);
 	}
 
 	/**
@@ -319,6 +355,19 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		}
 
 		this.latestSummarySequenceNumber = incrementalSummaryContext.latestSummarySequenceNumber;
+
+		// Build a reverse lookup map (referenceId → properties) for the latest summary so that
+		// computeHandlePathInLatestSummary can traverse the parent chain without iterating the whole map.
+		const latestSummaryRefIdMap: Map<ChunkReferenceId, ChunkSummaryProperties> = new Map();
+		const latestTracking = this.chunkTrackingPropertiesMap.get(
+			this.latestSummarySequenceNumber,
+		);
+		if (latestTracking !== undefined) {
+			for (const properties of latestTracking.values()) {
+				latestSummaryRefIdMap.set(properties.referenceId, properties);
+			}
+		}
+
 		this.trackedSummaryProperties = {
 			summarySequenceNumber: incrementalSummaryContext.summarySequenceNumber,
 			latestSummaryBasePath: incrementalSummaryContext.summaryPath,
@@ -326,10 +375,39 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			parentSummaryBuilder: builder,
 			fullTree,
 			stringify,
+			latestSummaryRefIdMap,
 		};
 		return ForestIncrementalSummaryBehavior.Incremental;
 	}
 
+	/**
+	 * Computes a chunk's path in the latest summary by traversing up the parent chain via
+	 * {@link latestSummaryRefIdMap}.
+	 *
+	 * Each {@link ChunkSummaryProperties.parentReferenceId} points to the chunk's parent as it
+	 * appeared in the summary where the entry was last written. Walking up the chain from the
+	 * chunk to the root produces the full path that can be used in a summary handle path.
+	 */
+	private computeHandlePathInLatestSummary(chunkProperties: ChunkSummaryProperties): string {
+		const { latestSummaryRefIdMap } = this.requireTrackingSummary();
+		const pathSegments: string[] = [];
+		let current: ChunkSummaryProperties | undefined = chunkProperties;
+		while (current !== undefined) {
+			pathSegments.push(`${current.referenceId}`);
+			if (current.parentReferenceId === undefined) {
+				break;
+			}
+			current = latestSummaryRefIdMap.get(current.parentReferenceId);
+			assert(
+				current !== undefined,
+				0xcf7 /* Parent chunk not found in latest summary tracking */,
+			);
+		}
+		// Segments are collected leaf-to-root and then reversed. The alternative would be to use unshift
+		// instead of push and reverse. However, using push and reverse is O(n) whereas using unshift would be O(n²).
+		return pathSegments.reverse().join("/");
+	}
+
 	/**
 	 * {@link IncrementalEncoder.encodeIncrementalField}
 	 * @remarks Returns an empty array if the field has no content.
@@ -344,8 +422,6 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		const chunkReferenceIds: ChunkReferenceId[] = [];
 		const chunks = this.getChunkAtCursor(cursor);
 		for (const chunk of chunks) {
-			let chunkProperties: ChunkSummaryProperties;
-
 			// Try and get the properties of the chunk from the latest successful summary.
 			// If it exists and the summary is not a full tree, use the properties to generate a summary handle.
 			// If it does not exist, encode the chunk and generate new properties for it.
@@ -354,28 +430,29 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				this.latestSummarySequenceNumber,
 				chunk,
 			);
+			let chunkReferenceId: ChunkReferenceId;
 			if (previousChunkProperties !== undefined && !trackedSummaryProperties.fullTree) {
-				chunkProperties = previousChunkProperties;
+				chunkReferenceId = previousChunkProperties.referenceId;
+				// Compute this chunk's path in the latest summary by traversing the parent chain.
+				// Using parentReferenceId traversal (rather than a stored path string) ensures the
+				// path is correct even when an ancestor was re-encoded in a prior summary and
+				// received a new referenceId — the stored summaryPath would have been stale in
+				// that case.
+				const handlePath = this.computeHandlePathInLatestSummary(previousChunkProperties);
 				trackedSummaryProperties.parentSummaryBuilder.addHandle(
-					`${chunkProperties.referenceId}`,
+					`${chunkReferenceId}`,
 					SummaryType.Tree,
-					`${trackedSummaryProperties.latestSummaryBasePath}/${chunkProperties.summaryPath}`,
+					`${trackedSummaryProperties.latestSummaryBasePath}/${handlePath}`,
 				);
 			} else {
 				// Generate a new reference ID for the chunk.
 				const newReferenceId: ChunkReferenceId = brand(this.nextReferenceId++);
+				chunkReferenceId = newReferenceId;
 
-				// Add the reference ID of this chunk to the chunk summary path and use the path as the summary path
-				// for the chunk in its summary properties.
-				// This is done before encoding the chunk so that the summary path is updated correctly when encoding
-				// any incremental chunks that are under this chunk.
+				// Add the reference ID of this chunk to the chunk summary path before encoding so
+				// that any incremental chunks in the subtree use the correct parent path.
 				trackedSummaryProperties.chunkSummaryPath.push(newReferenceId);
 
-				chunkProperties = {
-					referenceId: newReferenceId,
-					summaryPath: trackedSummaryProperties.chunkSummaryPath.join("/"),
-				};
-
 				const parentSummaryBuilder = trackedSummaryProperties.parentSummaryBuilder;
 				// Create a new summary builder for this chunk to build its summary tree which will be stored in the
 				// parent's summary tree under its reference ID.
@@ -400,13 +477,21 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				trackedSummaryProperties.chunkSummaryPath.pop();
 			}
 
+			// Get the parent reference ID from the current chunk summary path.
+			// For the root of the forest tree, the parent reference ID is undefined.
+			// For all other chunks, the parent reference ID is the last element in the current chunk summary path.
+			const chunkSummaryPathLength = trackedSummaryProperties.chunkSummaryPath.length;
+			const parentReferenceId: ChunkReferenceId | undefined =
+				chunkSummaryPathLength > 0
+					? trackedSummaryProperties.chunkSummaryPath[chunkSummaryPathLength - 1]
+					: undefined;
 			setInNestedMap(
 				this.chunkTrackingPropertiesMap,
 				trackedSummaryProperties.summarySequenceNumber,
 				chunk,
-				chunkProperties,
+				{ referenceId: chunkReferenceId, parentReferenceId },
 			);
-			chunkReferenceIds.push(chunkProperties.referenceId);
+			chunkReferenceIds.push(chunkReferenceId);
 		}
 		return chunkReferenceIds;
 	}
@@ -480,9 +565,9 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		referenceId: ChunkReferenceId,
 		chunkDecoder: (encoded: EncodedFieldBatchV2) => TreeChunk,
 	): TreeChunk {
-		const ChunkLoadProperties = this.loadedChunksMap.get(`${referenceId}`);
-		assert(ChunkLoadProperties !== undefined, 0xc86 /* Encoded incremental chunk not found */);
-		const chunk = chunkDecoder(ChunkLoadProperties.encodedContents);
+		const chunkLoadProperties = this.loadedChunksMap.get(`${referenceId}`);
+		assert(chunkLoadProperties !== undefined, 0xc86 /* Encoded incremental chunk not found */);
+		const chunk = chunkDecoder(chunkLoadProperties.encodedContents);
 
 		// Account for the reference about to be added in `chunkTrackingPropertiesMap`
 		// to ensure that no other users of this chunk think they have unique ownership.
@@ -493,7 +578,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		// when a new client starts to summarize.
 		setInNestedMap(this.chunkTrackingPropertiesMap, this.initialSequenceNumber, chunk, {
 			referenceId,
-			summaryPath: ChunkLoadProperties.summaryPath,
+			parentReferenceId: chunkLoadProperties.parentReferenceId,
 		});
 		return chunk;
 	}

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.100.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,64 @@ 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). Setting the field to `undefined` is rejected because the stored schema still declares the field as required.
+	 * 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.stagedOptional} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStaticsAlpha.stagedOptional} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 */
+	readonly stagedOptionalRecursive: <
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+		const TCustomMetadata = unknown,
+	>(
+		t: T,
+		props?: Omit<
+			FieldPropsAlpha<TCustomMetadata>,
+			"defaultProvider" | "stagedOptionalUpgrade"
+		>,
+	) => FieldSchemaAlphaUnsafe<
+		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 +284,27 @@ 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,
+	stagedOptionalRecursive: stagedOptional as SchemaStaticsAlpha["stagedOptionalRecursive"],
 };
 
 /**
@@ -448,7 +524,27 @@ 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;
+
+	/**
+	 * {@inheritdoc SchemaStaticsAlpha.stagedOptionalRecursive}
+	 */
+	public readonly stagedOptionalRecursive = schemaStaticsAlpha.stagedOptionalRecursive;
+
+	/**
+	 * {@inheritdoc SchemaStaticsAlpha.stagedOptionalRecursive}
+	 */
+	public static readonly stagedOptionalRecursive = schemaStaticsAlpha.stagedOptionalRecursive;
+
+	/**
+	 * 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,