@fluidframework/tree 2.42.0 → 2.43.0-343119

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

@@ -8,6 +8,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type {
+	IExperimentalIncrementalSummaryContext,
 	ISummaryTreeWithStats,
 	ITelemetryContext,
 } from "@fluidframework/runtime-definitions/internal";
@@ -49,22 +50,14 @@ export class EditManagerSummarizer<TChangeset> implements Summarizable {
 		private readonly schemaAndPolicy?: SchemaAndPolicy,
 	) {}
 
-	public getAttachSummary(
-		stringify: SummaryElementStringifier,
-		fullTree?: boolean,
-		trackState?: boolean,
-		telemetryContext?: ITelemetryContext,
-	): ISummaryTreeWithStats {
-		return this.summarizeCore(stringify);
-	}
-
-	public async summarize(
-		stringify: SummaryElementStringifier,
-		fullTree?: boolean,
-		trackState?: boolean,
-		telemetryContext?: ITelemetryContext,
-	): Promise<ISummaryTreeWithStats> {
-		return this.summarizeCore(stringify);
+	public summarize(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+	}): ISummaryTreeWithStats {
+		return this.summarizeCore(props.stringify);
 	}
 
 	private summarizeCore(stringify: SummaryElementStringifier): ISummaryTreeWithStats {

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

@@ -212,20 +212,30 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		serializer: IFluidSerializer,
 		telemetryContext?: ITelemetryContext,
 		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
+		fullTree?: boolean,
 	): ISummaryTreeWithStats {
 		const builder = new SummaryTreeBuilder();
 		const summarizableBuilder = new SummaryTreeBuilder();
 		// Merge the summaries of all summarizables together under a single ISummaryTree
 		for (const s of this.summarizables) {
+			// Add the summarizable's path in the summary tree to the incremental summary context's
+			// summary path, so that the summarizable can use it to generate incremental summaries.
+			const childIncrementalSummaryContext =
+				incrementalSummaryContext === undefined
+					? undefined
+					: {
+							...incrementalSummaryContext,
+							summaryPath: `${incrementalSummaryContext.summaryPath}/${summarizablesTreeKey}/${s.key}`,
+						};
 			summarizableBuilder.addWithStats(
 				s.key,
-				s.getAttachSummary(
-					(contents) => serializer.stringify(contents, this.sharedObject.handle),
-					undefined,
-					undefined,
+				s.summarize({
+					stringify: (contents: unknown) =>
+						serializer.stringify(contents, this.sharedObject.handle),
+					fullTree,
 					telemetryContext,
-					incrementalSummaryContext,
-				),
+					incrementalSummaryContext: childIncrementalSummaryContext,
+				}),
 			);
 		}
 
@@ -434,28 +444,27 @@ export interface Summarizable {
 	 */
 	readonly key: string;
 
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).getAttachSummary}
-	 * @param stringify - Serializes the contents of the component (including {@link (IFluidHandle:interface)}s) for storage.
-	 */
-	getAttachSummary(
-		stringify: SummaryElementStringifier,
-		fullTree?: boolean,
-		trackState?: boolean,
-		telemetryContext?: ITelemetryContext,
-		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
-	): ISummaryTreeWithStats;
-
 	/**
 	 * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).summarize}
 	 * @param stringify - Serializes the contents of the component (including {@link (IFluidHandle:interface)}s) for storage.
+	 * @param fullTree - A flag indicating whether the attempt should generate a full
+	 * summary tree without any handles for unchanged subtrees. It should only be set to true when generating
+	 * a summary from the entire container. The default value is false.
+	 * @param trackState - An optimization for tracking state of objects across summaries. If the state
+	 * of an object did not change since last successful summary, an
+	 * {@link @fluidframework/protocol-definitions#ISummaryHandle} can be used
+	 * instead of re-summarizing it. If this is `false`, the expectation is that you should never
+	 * send an `ISummaryHandle`, since you are not expected to track state. The default value is true.
+	 * @param telemetryContext - See {@link @fluidframework/runtime-definitions#ITelemetryContext}.
+	 * @param incrementalSummaryContext - See {@link @fluidframework/runtime-definitions#IExperimentalIncrementalSummaryContext}.
 	 */
-	summarize(
-		stringify: SummaryElementStringifier,
-		fullTree?: boolean,
-		trackState?: boolean,
-		telemetryContext?: ITelemetryContext,
-	): Promise<ISummaryTreeWithStats>;
+	summarize(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+	}): ISummaryTreeWithStats;
 
 	/**
 	 * Allows the component to perform custom loading. The storage service is scoped to this component and therefore

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

@@ -275,7 +275,7 @@ export class SchemaCompatibilityTester {
 				}
 			}
 
-			return { kind: original.kind, types };
+			return { kind: original.kind, types, persistedMetadata: undefined };
 		}
 		return original;
 	}

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

@@ -32,7 +32,7 @@ import type { UnionToTuple } from "../../util/index.js";
  * This is commonly used in unions when the only information needed is which kind of node the value is.
  * Enums are a common example of this pattern.
  * @see {@link adaptEnum}
- * @alpha
+ * @beta
  */
 // Return type is intentionally derived.
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -107,7 +107,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * @privateRemarks
  * Maybe provide `SchemaFactory.nested` to ease creating nested scopes?
  * @see {@link enumFromStrings} for a similar function that works on arrays of strings instead of an enum.
- * @alpha
+ * @beta
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function adaptEnum<
@@ -186,7 +186,7 @@ export function adaptEnum<
  * class Parent extends schemaFactory.object("Parent", { mode: Mode.schema }) {}
  * ```
  * @see {@link adaptEnum} for a similar function that works on enums instead of arrays of strings.
- * @alpha
+ * @beta
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function enumFromStrings<

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

@@ -56,13 +56,14 @@ import {
 	createFieldSchema,
 	type DefaultProvider,
 	getDefaultProvider,
-	type NodeSchemaOptions,
 	markSchemaMostDerived,
 	type FieldSchemaAlpha,
 	type ImplicitAnnotatedAllowedTypes,
 	type UnannotateImplicitAllowedTypes,
 	type UnannotateSchemaRecord,
+	type NodeSchemaOptionsAlpha,
 	normalizeAllowedTypes,
+	type FieldPropsAlpha,
 } from "../schemaTypes.js";
 
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
@@ -101,7 +102,7 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
  * @alpha
  */
 export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown>
-	extends NodeSchemaOptions<TCustomMetadata> {
+	extends NodeSchemaOptionsAlpha<TCustomMetadata> {
 	/**
 	 * Allow nodes typed with this object node schema to contain optional fields that are not present in the schema declaration.
 	 * Such nodes can come into existence either via import APIs (see remarks) or by way of collaboration with another client
@@ -147,8 +148,12 @@ export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown>
 	allowUnknownOptionalFields?: boolean;
 }
 
+/**
+ * Default options for Object node schema creation.
+ * @remarks Omits parameters that are not relevant for common use cases.
+ */
 export const defaultSchemaFactoryObjectOptions: Required<
-	Omit<SchemaFactoryObjectOptions, "metadata">
+	Omit<SchemaFactoryObjectOptions, "metadata" | "persistedMetadata">
 > = {
 	allowUnknownOptionalFields: false,
 };
@@ -307,7 +312,7 @@ const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => []);
 
 function optional<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;
 
 function optional<
@@ -315,7 +320,7 @@ function optional<
 	const TCustomMetadata = unknown,
 >(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
 
 function optional<
@@ -323,7 +328,7 @@ function optional<
 	const TCustomMetadata = unknown,
 >(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {
 	return createFieldSchema(FieldKind.Optional, t, {
 		defaultProvider: defaultOptionalProvider,
@@ -333,7 +338,7 @@ function optional<
 
 function required<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;
 
 function required<
@@ -341,7 +346,7 @@ function required<
 	const TCustomMetadata = unknown,
 >(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
 
 function required<
@@ -349,7 +354,7 @@ function required<
 	const TCustomMetadata = unknown,
 >(
 	t: T,
-	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 ): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {
 	return createFieldSchema(FieldKind.Required, t, props);
 }
@@ -377,7 +382,7 @@ export const schemaStaticsBase = {
 		const TCustomMetadata = unknown,
 	>(
 		t: T,
-		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 	): FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata> => {
 		return createFieldSchemaUnsafe(FieldKind.Optional, t, {
 			defaultProvider: defaultOptionalProvider,
@@ -390,7 +395,7 @@ export const schemaStaticsBase = {
 		const TCustomMetadata = unknown,
 	>(
 		t: T,
-		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
 	): FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata> => {
 		return createFieldSchemaUnsafe(FieldKind.Required, t, props);
 	},

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

@@ -23,7 +23,7 @@ import type {
 	ImplicitAnnotatedAllowedTypes,
 	ImplicitAnnotatedFieldSchema,
 	ImplicitFieldSchema,
-	NodeSchemaOptions,
+	NodeSchemaOptionsAlpha,
 } from "../schemaTypes.js";
 import type { RestrictiveStringRecord } from "../../util/index.js";
 import type { NodeKind, TreeNodeSchemaClass } from "../core/index.js";
@@ -88,6 +88,7 @@ export class SchemaFactoryAlpha<
 			options?.allowUnknownOptionalFields ??
 				defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
 			options?.metadata,
+			options?.persistedMetadata,
 		);
 	}
 
@@ -148,7 +149,7 @@ export class SchemaFactoryAlpha<
 	}
 
 	/**
-	 * {@inheritDoc SchemaStatics.optional}
+	 * {@inheritDoc SchemaStatics.leaves}
 	 */
 	public static override readonly leaves = schemaStatics.leaves;
 
@@ -167,11 +168,41 @@ export class SchemaFactoryAlpha<
 	 */
 	public static override readonly optionalRecursive = schemaStatics.optionalRecursive;
 
+	/**
+	 * {@inheritDoc SchemaStatics.requiredRecursive}
+	 */
+	public static override readonly requiredRecursive = schemaStatics.requiredRecursive;
+
 	/**
 	 * Like {@link SchemaFactory.identifier} but static and a factory function that can be provided {@link FieldProps}.
 	 */
 	public static readonly identifier = schemaStatics.identifier;
 
+	/**
+	 * {@inheritDoc SchemaStatics.leaves}
+	 */
+	public override readonly leaves = schemaStatics.leaves;
+
+	/**
+	 * {@inheritDoc SchemaStatics.optional}
+	 */
+	public override readonly optional = schemaStatics.optional;
+
+	/**
+	 * {@inheritDoc SchemaStatics.required}
+	 */
+	public override readonly required = schemaStatics.required;
+
+	/**
+	 * {@inheritDoc SchemaStatics.optionalRecursive}
+	 */
+	public override readonly optionalRecursive = schemaStatics.optionalRecursive;
+
+	/**
+	 * {@inheritDoc SchemaStatics.requiredRecursive}
+	 */
+	public override readonly requiredRecursive = schemaStatics.requiredRecursive;
+
 	/**
 	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
 	 *
@@ -193,9 +224,16 @@ export class SchemaFactoryAlpha<
 	>(
 		name: Name,
 		allowedTypes: T,
-		options?: NodeSchemaOptions<TCustomMetadata>,
+		options?: NodeSchemaOptionsAlpha<TCustomMetadata>,
 	): MapNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
-		return mapSchema(this.scoped2(name), allowedTypes, true, true, options?.metadata);
+		return mapSchema(
+			this.scoped2(name),
+			allowedTypes,
+			true,
+			true,
+			options?.metadata,
+			options?.persistedMetadata,
+		);
 	}
 
 	/**
@@ -206,7 +244,7 @@ export class SchemaFactoryAlpha<
 		Name extends TName,
 		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
-	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
+	>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {
 		return this.mapAlpha(
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,
@@ -237,9 +275,16 @@ export class SchemaFactoryAlpha<
 	>(
 		name: Name,
 		allowedTypes: T,
-		options?: NodeSchemaOptions<TCustomMetadata>,
+		options?: NodeSchemaOptionsAlpha<TCustomMetadata>,
 	): ArrayNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
-		return arraySchema(this.scoped2(name), allowedTypes, true, true, options?.metadata);
+		return arraySchema(
+			this.scoped2(name),
+			allowedTypes,
+			true,
+			true,
+			options?.metadata,
+			options?.persistedMetadata,
+		);
 	}
 
 	/**
@@ -250,7 +295,7 @@ export class SchemaFactoryAlpha<
 		const Name extends TName,
 		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
-	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
+	>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {
 		return this.arrayAlpha(
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,

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

@@ -12,7 +12,7 @@ import {
 } from "../../feature-libraries/index.js";
 import {
 	clientVersionToSchemaVersion,
-	type Format,
+	type FormatV1,
 	// eslint-disable-next-line import/no-internal-modules
 } from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
@@ -58,8 +58,8 @@ export function extractPersistedSchema(
 	oldestCompatibleClient: FluidClientVersion,
 ): JsonCompatible {
 	const stored = simpleToStoredSchema(schema);
-	const writeVersion = clientVersionToSchemaVersion(oldestCompatibleClient);
-	return encodeTreeSchema(stored, writeVersion);
+	const schemaWriteVersion = clientVersionToSchemaVersion(oldestCompatibleClient);
+	return encodeTreeSchema(stored, schemaWriteVersion);
 }
 
 /**
@@ -100,7 +100,7 @@ export function comparePersistedSchema(
 	// Any version can be passed down to makeSchemaCodec here.
 	// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.
 	const schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);
-	const stored = schemaCodec.decode(persisted as Format);
+	const stored = schemaCodec.decode(persisted as FormatV1);
 	const viewSchema = new SchemaCompatibilityTester(
 		defaultSchemaPolicy,
 		{},

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

@@ -26,7 +26,10 @@
  */
 export interface TreeChangeEvents {
 	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.
+	 * Emitted by a node if any changes affected the node.
+	 *
+	 * This event is emitted after all the changes in a batch have been applied to the whole tree.
+	 * This means that a handler for this event will be able to read the updated state of the tree.
 	 *
 	 * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).
 	 *
@@ -65,8 +68,10 @@ export interface TreeChangeEvents {
 	nodeChanged(unstable?: unknown): void;
 
 	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
-	 * subtree rooted at it.
+	 * Emitted by a node if something changed anywhere in the subtree rooted at it.
+	 *
+	 * This event is emitted after all the changes in a batch have been applied to the whole tree.
+	 * This means that a handler for this event will be able to read the updated state of the tree.
 	 *
 	 * @remarks
 	 * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.

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

@@ -63,6 +63,7 @@ export function toSimpleTreeSchema(
 					allowedTypesIdentifiers: normalizedSchema.allowedTypesIdentifiers,
 					kind: normalizedSchema.kind,
 					metadata: normalizedSchema.metadata,
+					persistedMetadata: normalizedSchema.persistedMetadata,
 				} satisfies SimpleFieldSchema)
 			: normalizedSchema,
 		definitions,
@@ -94,6 +95,7 @@ function copySimpleLeafSchema(schema: SimpleLeafNodeSchema): SimpleLeafNodeSchem
 		kind: NodeKind.Leaf,
 		leafKind: schema.leafKind,
 		metadata: schema.metadata,
+		persistedMetadata: schema.persistedMetadata,
 	};
 }
 
@@ -104,6 +106,7 @@ function copySimpleMapOrArraySchema(
 		kind: schema.kind,
 		allowedTypesIdentifiers: schema.allowedTypesIdentifiers,
 		metadata: schema.metadata,
+		persistedMetadata: schema.persistedMetadata,
 	};
 }
 
@@ -115,6 +118,7 @@ function copySimpleObjectSchema(schema: SimpleObjectNodeSchema): SimpleObjectNod
 			kind: field.kind,
 			allowedTypesIdentifiers: field.allowedTypesIdentifiers,
 			metadata: field.metadata,
+			persistedMetadata: field.persistedMetadata,
 			storedKey: field.storedKey,
 		});
 	}
@@ -123,5 +127,6 @@ function copySimpleObjectSchema(schema: SimpleObjectNodeSchema): SimpleObjectNod
 		kind: NodeKind.Object,
 		fields,
 		metadata: schema.metadata,
+		persistedMetadata: schema.persistedMetadata,
 	};
 }

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

@@ -401,7 +401,7 @@ export function tryDisposeTreeNode(anchorNode: AnchorNode): void {
  */
 export function getSimpleNodeSchemaFromInnerNode(innerNode: InnerNode): TreeNodeSchema {
 	const context: Context = getSimpleContextFromInnerNode(innerNode);
-	return context.schema.get(innerNode.schema) ?? fail(0xb3f /* missing schema from context */);
+	return context.schema.get(innerNode.type) ?? fail(0xb3f /* missing schema from context */);
 }
 
 /**

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

@@ -10,10 +10,9 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	type AnchorEvents,
-	EmptyKey,
+	dummyRoot,
 	type FieldKey,
 	type FieldKindIdentifier,
-	forbiddenFieldKindIdentifier,
 	type ITreeCursorSynchronous,
 	type NodeData,
 	type NormalizedFieldUpPath,
@@ -49,8 +48,10 @@ import {
 	type MapTreeFieldViewGeneric,
 	type MapTreeNodeViewGeneric,
 	type HydratedFlexTreeNode,
+	cursorForMapTreeField,
+	type MinimalFieldMap,
 } from "../../feature-libraries/index.js";
-import { brand, filterIterable, getOrCreate } from "../../util/index.js";
+import { brand, filterIterable, getOrCreate, mapIterable } from "../../util/index.js";
 
 import type { Context } from "./context.js";
 import type { ContextualFieldProvider } from "../schemaTypes.js";
@@ -62,10 +63,7 @@ interface UnhydratedTreeSequenceFieldEditBuilder
 type UnhydratedFlexTreeNodeEvents = Pick<AnchorEvents, "childrenChangedAfterBatch">;
 
 /** A node's parent field and its index in that field */
-interface LocationInField {
-	readonly parent: FlexTreeField;
-	readonly index: number;
-}
+type LocationInField = FlexTreeNode["parentField"];
 
 /**
  * The {@link Unhydrated} implementation of {@link FlexTreeNode}.
@@ -140,15 +138,16 @@ export class UnhydratedFlexTreeNode
 	 * Due to having to detect if a field is empty, this forces the evaluation of any pending defaults in the fields.
 	 * Use {@link allFieldsLazy} to avoid evaluating pending defaults.
 	 */
-	public readonly fields: Pick<
-		Map<FieldKey, UnhydratedFlexTreeField>,
-		typeof Symbol.iterator | "get"
-	> = {
+	public readonly fields: MinimalFieldMap<UnhydratedFlexTreeField> = {
 		get: (key: FieldKey): UnhydratedFlexTreeField | undefined => this.tryGetField(key),
 		[Symbol.iterator]: (): IterableIterator<[FieldKey, UnhydratedFlexTreeField]> =>
 			filterIterable(this.fieldsAll, ([, field]) => field.length > 0),
 	};
 
+	public [Symbol.iterator](): IterableIterator<UnhydratedFlexTreeField> {
+		return mapIterable(this.fields, ([, field]) => field)[Symbol.iterator]();
+	}
+
 	/**
 	 * Gets all fields, without filtering out empty ones.
 	 * @remarks
@@ -162,10 +161,6 @@ export class UnhydratedFlexTreeNode
 		return this.data.type;
 	}
 
-	public get schema(): TreeNodeSchemaIdentifier {
-		return this.data.type;
-	}
-
 	private getOrCreateField(key: FieldKey): UnhydratedFlexTreeField {
 		return getOrCreate(this.fieldsAll, key, () => {
 			const stored = this.storedSchema.getFieldSchema(key).kind;
@@ -239,10 +234,6 @@ export class UnhydratedFlexTreeNode
 		return this.getOrCreateField(fieldKey);
 	}
 
-	public boxedIterator(): IterableIterator<FlexTreeField> {
-		return Array.from(this.fields, ([key, field]) => field)[Symbol.iterator]();
-	}
-
 	public keys(): IterableIterator<FieldKey> {
 		return Array.from(this.fields, ([key]) => key)[Symbol.iterator]();
 	}
@@ -288,31 +279,16 @@ export class UnhydratedContext implements FlexTreeContext {
  * However, this field cannot be used in any practical way because it is empty, i.e. it does not actually contain the children that claim to be parented under it.
  * It has the "empty" schema and it will always contain zero children if queried.
  * Any nodes with this location will have a dummy parent index of `-1`.
+ *
+ * TODO: make this make sense.
  */
 const unparentedLocation: LocationInField = {
 	parent: {
-		[flexTreeMarker]: FlexTreeEntityKind.Field as const,
-		length: 0,
-		key: EmptyKey,
+		key: dummyRoot,
 		parent: undefined,
-		is<TKind2 extends FlexFieldKind>(kind: TKind2) {
-			return this.schema === kind.identifier;
-		},
-		boxedIterator(): IterableIterator<FlexTreeNode> {
-			return [].values();
-		},
-		boxedAt(index: number): FlexTreeNode | undefined {
-			return undefined;
-		},
-		schema: brand(forbiddenFieldKindIdentifier),
-		get context(): never {
-			return fail(0xb48 /* unsupported */);
-		},
-		getFieldPath() {
-			fail(0xb49 /* unsupported */);
-		},
+		schema: brand(FieldKinds.optional.identifier),
 	},
-	index: -1,
+	index: 0,
 };
 
 /**
@@ -347,6 +323,12 @@ export class UnhydratedFlexTreeField
 		}
 	}
 
+	public borrowCursor(): ITreeCursorSynchronous {
+		return cursorForMapTreeField<MapTreeNodeViewGeneric<UnhydratedFlexTreeNode>>(
+			this.children,
+		);
+	}
+
 	private getPendingDefault(): ContextualFieldProvider | undefined {
 		return !Array.isArray(this.lazyChildren) ? this.lazyChildren : undefined;
 	}
@@ -389,10 +371,6 @@ export class UnhydratedFlexTreeField
 		return this.schema === kind.identifier;
 	}
 
-	public boxedIterator(): IterableIterator<UnhydratedFlexTreeNode> {
-		return this.children[Symbol.iterator]();
-	}
-
 	public boxedAt(index: number): FlexTreeNode | undefined {
 		const i = indexForAt(index, this.length);
 		if (i === undefined) {
@@ -403,7 +381,7 @@ export class UnhydratedFlexTreeField
 	}
 
 	public [Symbol.iterator](): IterableIterator<UnhydratedFlexTreeNode> {
-		return this.boxedIterator();
+		return this.children[Symbol.iterator]();
 	}
 
 	/**

package/src/simple-tree/index.ts

@@ -131,6 +131,7 @@ export type {
 	SimpleArrayNodeSchema,
 	SimpleObjectNodeSchema,
 	SimpleNodeSchemaBase,
+	SimpleNodeSchemaBaseAlpha,
 	SimpleObjectFieldSchema,
 } from "./simpleSchema.js";
 export {
@@ -164,6 +165,7 @@ export {
 	type NodeBuilderData,
 	type DefaultProvider,
 	type FieldProps,
+	type FieldPropsAlpha,
 	normalizeFieldSchema,
 	areFieldSchemaEqual,
 	areImplicitFieldSchemaEqual,
@@ -179,6 +181,7 @@ export {
 	type ReadableField,
 	type ReadSchema,
 	type NodeSchemaOptions,
+	type NodeSchemaOptionsAlpha,
 	type NodeSchemaMetadata,
 	evaluateLazySchema,
 } from "./schemaTypes.js";

package/src/simple-tree/leafNodeSchema.ts

@@ -15,6 +15,7 @@ import {
 import { NodeKind, type TreeNodeSchema, type TreeNodeSchemaNonClass } from "./core/index.js";
 import type { NodeSchemaMetadata, TreeLeafValue } from "./schemaTypes.js";
 import type { SimpleLeafNodeSchema } from "./simpleSchema.js";
+import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
 
 /**
  * Instances of this class are schema for leaf nodes.
@@ -50,6 +51,7 @@ export class LeafNodeSchema<Name extends string, const T extends ValueSchema>
 	public readonly leafKind: ValueSchema;
 
 	public readonly metadata: NodeSchemaMetadata = {};
+	public readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined;
 
 	public constructor(name: Name, t: T) {
 		this.identifier = name;