@fluidframework/tree 2.63.0-359734 → 2.63.0-359962

package/src/feature-libraries/chunked-forest/codec/schemaBasedEncode.ts

@@ -16,7 +16,6 @@ import {
 	ValueSchema,
 	Multiplicity,
 	identifierFieldKindIdentifier,
-	type FieldKey,
 } from "../../../core/index.js";
 import type { FullSchemaPolicy } from "../../modular-schema/index.js";
 
@@ -35,6 +34,7 @@ import type { FieldBatch } from "./fieldBatch.js";
 import { type EncodedFieldBatch, type EncodedValueShape, SpecialField } from "./format.js";
 import type { IncrementalEncoder } from "./codecs.js";
 import { NodeShapeBasedEncoder } from "./nodeEncoder.js";
+import { defaultIncrementalEncodingPolicy } from "./incrementalEncodingPolicy.js";
 
 /**
  * Encode data from `fieldBatch` in into an `EncodedChunk`.
@@ -134,14 +134,11 @@ export function getNodeEncoder(
 		// consider moving some optional and sequence fields to extra fields if they are commonly empty
 		// to reduce encoded size.
 
-		const shouldEncodeFieldIncrementallyLocal = (
-			nodeIdentifier: TreeNodeSchemaIdentifier,
-			fieldKey: FieldKey,
-		): boolean =>
-			incrementalEncoder?.shouldEncodeFieldIncrementally(nodeIdentifier, fieldKey) ?? false;
+		const shouldEncodeIncrementally =
+			incrementalEncoder?.shouldEncodeIncrementally ?? defaultIncrementalEncodingPolicy;
 		const objectNodeFields: KeyedFieldEncoder[] = [];
 		for (const [key, field] of schema.objectNodeFields ?? []) {
-			const fieldEncoder = shouldEncodeFieldIncrementallyLocal(schemaName, key)
+			const fieldEncoder = shouldEncodeIncrementally(schemaName, key)
 				? incrementalFieldEncoder
 				: fieldBuilder.fieldEncoderFromSchema(field);
 			objectNodeFields.push({

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

@@ -25,5 +25,7 @@ export {
 	fluidVersionToFieldBatchCodecWriteVersion,
 	type IncrementalEncoderDecoder,
 	type ChunkReferenceId,
+	type IncrementalEncodingPolicy,
+	defaultIncrementalEncodingPolicy,
 } from "./codec/index.js";
 export { emptyChunk } from "./emptyChunk.js";

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -398,7 +398,7 @@ export interface FlexTreeOptionalField extends FlexTreeField {
 export type FlexTreeTypedField<Kind extends FlexFieldKind> =
 	Kind extends typeof FieldKinds.sequence
 		? FlexTreeSequenceField
-		: Kind extends typeof FieldKinds.required
+		: Kind extends typeof FieldKinds.required | typeof FieldKinds.identifier
 			? FlexTreeRequiredField
 			: Kind extends typeof FieldKinds.optional
 				? FlexTreeOptionalField

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

@@ -23,7 +23,6 @@ import {
 	type ITreeSubscriptionCursor,
 	type RevisionTagCodec,
 	TreeNavigationResult,
-	type TreeNodeSchemaIdentifier,
 	applyDelta,
 	forEachField,
 	makeDetachedFieldIndex,
@@ -36,7 +35,12 @@ import type {
 import { idAllocatorFromMaxId, type JsonCompatible } from "../../util/index.js";
 // eslint-disable-next-line import/no-internal-modules
 import { chunkFieldSingle, defaultChunkPolicy } from "../chunked-forest/chunkTree.js";
-import type { FieldBatchCodec, FieldBatchEncodingContext } from "../chunked-forest/index.js";
+import {
+	defaultIncrementalEncodingPolicy,
+	type FieldBatchCodec,
+	type FieldBatchEncodingContext,
+	type IncrementalEncodingPolicy,
+} from "../chunked-forest/index.js";
 
 import { type ForestCodec, makeForestSummarizerCodec } from "./codec.js";
 import {
@@ -74,23 +78,15 @@ export class ForestSummarizer implements Summarizable {
 		private readonly encoderContext: FieldBatchEncodingContext,
 		options: CodecWriteOptions,
 		private readonly idCompressor: IIdCompressor,
-		shouldEncodeFieldIncrementally?: (
-			nodeIdentifier: TreeNodeSchemaIdentifier,
-			fieldKey: FieldKey,
-		) => boolean,
+		shouldEncodeIncrementally: IncrementalEncodingPolicy = defaultIncrementalEncodingPolicy,
 	) {
 		// TODO: this should take in CodecWriteOptions, and use it to pick the write version.
 		this.codec = makeForestSummarizerCodec(options, fieldBatchCodec);
-
-		const shouldEncodeFieldIncrementallyLocal = (
-			nodeIdentifier: TreeNodeSchemaIdentifier,
-			fieldKey: FieldKey,
-		): boolean => shouldEncodeFieldIncrementally?.(nodeIdentifier, fieldKey) ?? false;
 		this.incrementalSummaryBuilder = new ForestIncrementalSummaryBuilder(
 			encoderContext.encodeType ===
 				TreeCompressionStrategyExtended.CompressedIncremental /* enableIncrementalSummary */,
 			(cursor: ITreeCursorSynchronous) => this.forest.chunkField(cursor),
-			shouldEncodeFieldIncrementallyLocal,
+			shouldEncodeIncrementally,
 		);
 	}
 

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

@@ -20,13 +20,10 @@ import type {
 	ChunkReferenceId,
 	EncodedFieldBatch,
 	IncrementalEncoderDecoder,
+	IncrementalEncodingPolicy,
 	TreeChunk,
 } from "../chunked-forest/index.js";
-import type {
-	FieldKey,
-	ITreeCursorSynchronous,
-	TreeNodeSchemaIdentifier,
-} from "../../core/index.js";
+import type { ITreeCursorSynchronous } from "../../core/index.js";
 import { SummaryType } from "@fluidframework/driver-definitions";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type { ISnapshotTree } from "@fluidframework/driver-definitions/internal";
@@ -263,13 +260,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 	public constructor(
 		private readonly enableIncrementalSummary: boolean,
 		private readonly getChunkAtCursor: (cursor: ITreeCursorSynchronous) => TreeChunk,
-		/**
-		 * {@link IncrementalEncoder.shouldEncodeFieldIncrementally}
-		 */
-		public readonly shouldEncodeFieldIncrementally: (
-			nodeIdentifier: TreeNodeSchemaIdentifier,
-			fieldKey: FieldKey,
-		) => boolean,
+		public readonly shouldEncodeIncrementally: IncrementalEncodingPolicy,
 	) {}
 
 	/**

package/src/feature-libraries/index.ts

@@ -110,6 +110,8 @@ export {
 	fluidVersionToFieldBatchCodecWriteVersion,
 	type FieldBatchEncodingContext,
 	emptyChunk,
+	type IncrementalEncodingPolicy,
+	defaultIncrementalEncodingPolicy,
 } from "./chunked-forest/index.js";
 
 export {

package/src/index.ts

@@ -137,6 +137,13 @@ export {
 	type ArrayNodeCustomizableSchemaUnsafe,
 	type MapNodeCustomizableSchemaUnsafe,
 	type TreeRecordNodeUnsafe,
+	type UnannotateAllowedTypeUnsafe,
+	type AnnotatedAllowedTypeUnsafe,
+	type AnnotatedAllowedTypesUnsafe,
+	type AllowedTypesFullUnsafe,
+	type AllowedTypesFullFromMixedUnsafe,
+	type UnannotateAllowedTypesListUnsafe,
+	type AnnotateAllowedTypesListUnsafe,
 	// System types (not in Internal types for various reasons, like doc links or cannot be named errors).
 	type typeSchemaSymbol,
 	type TreeNodeSchemaNonClass,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.63.0-359734";
+export const pkgVersion = "2.63.0-359962";

package/src/shared-tree/independentView.ts

@@ -26,6 +26,7 @@ import {
 	type FieldBatchEncodingContext,
 	defaultSchemaPolicy,
 	TreeCompressionStrategy,
+	defaultIncrementalEncodingPolicy,
 } from "../feature-libraries/index.js";
 // eslint-disable-next-line import/no-internal-modules
 import type { Format } from "../feature-libraries/schema-index/formatV1.js";
@@ -67,6 +68,7 @@ export function independentView<const TSchema extends ImplicitFieldSchema>(
 		options.forest ?? defaultSharedTreeOptions.forest,
 		schema,
 		idCompressor,
+		defaultIncrementalEncodingPolicy,
 	);
 	const checkout = createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, {
 		forest,
@@ -144,6 +146,7 @@ export function independentInitializedViewInternal<const TSchema extends Implici
 		options.forest ?? defaultSharedTreeOptions.forest,
 		schemaRepository,
 		idCompressor,
+		defaultIncrementalEncodingPolicy,
 	);
 
 	const checkout = createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, {

package/src/shared-tree/schematizingTreeView.ts

@@ -12,13 +12,17 @@ import type {
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { anchorSlot } from "../core/index.js";
+import { anchorSlot, rootFieldKey } from "../core/index.js";
 import {
 	type NodeIdentifierManager,
 	defaultSchemaPolicy,
 	cursorForMapTreeField,
 	TreeStatus,
 	Context,
+	type FlexTreeOptionalField,
+	type FlexTreeUnknownUnboxed,
+	FieldKinds,
+	type FlexTreeRequiredField,
 } from "../feature-libraries/index.js";
 import {
 	type ImplicitFieldSchema,
@@ -38,7 +42,7 @@ import {
 	type UnsafeUnknownSchema,
 	type TreeBranch,
 	type TreeBranchEvents,
-	getOrCreateInnerNode,
+	getInnerNode,
 	getKernel,
 	type VoidTransactionCallbackStatus,
 	type TransactionCallbackStatus,
@@ -117,6 +121,11 @@ export class SchematizingSimpleTreeView<
 	 */
 	private midUpgrade = false;
 
+	/**
+	 * Hydration work deferred until Context has been created.
+	 */
+	private pendingHydration?: () => void;
+
 	private readonly rootFieldSchema: FieldSchema;
 	public readonly breaker: Breakable;
 
@@ -174,6 +183,13 @@ export class SchematizingSimpleTreeView<
 
 		this.runSchemaEdit(() => {
 			const schema = toInitialSchema(this.config.schema);
+			// This has to be the contextless version, since when "initialize" is called (right after this),
+			// it will do a schema change which would dispose of the current context (see inside `update`).
+			// Thus using the current context (if any) would hydrate nodes then
+			// immediately dispose them instead of having them actually be useable after initialize.
+			// For this to work,
+			// the hydration must be deferred until after the content is inserted into the tree and the final schema change is done (for required roots),
+			// but before any user event could could run.
 			const mapTree = prepareForInsertionContextless(
 				content as InsertableContent | undefined,
 				this.rootFieldSchema,
@@ -183,6 +199,19 @@ export class SchematizingSimpleTreeView<
 				},
 				this,
 				schema.rootFieldSchema,
+				(batches, doHydration) => {
+					assert(this.pendingHydration === undefined, "pendingHydration already set");
+					this.pendingHydration = () => {
+						assert(batches.length <= 1, "initialize should at most one hydration batch");
+						for (const batch of batches) {
+							doHydration(batch, {
+								parent: undefined,
+								parentField: rootFieldKey,
+								parentIndex: 0,
+							});
+						}
+					};
+				},
 			);
 
 			this.checkout.transaction.start();
@@ -350,7 +379,10 @@ export class SchematizingSimpleTreeView<
 				// TODO: provide a better event: this.view.flexTree.on(????) and/or integrate with with the normal event code paths.
 
 				// Track what the root was before to be able to detect changes.
-				let lastRoot: ReadableField<TRootSchema> = this.root;
+				// This uses the flex tree root to avoid demanding the simple-tree TreeNode when it might not be hydrated yet.
+				let lastRoot: FlexTreeUnknownUnboxed | undefined = (
+					this.flexTreeContext.root as FlexTreeOptionalField
+				).content;
 
 				this.flexTreeViewUnregisterCallbacks.add(
 					this.checkout.events.on("afterBatch", () => {
@@ -359,8 +391,8 @@ export class SchematizingSimpleTreeView<
 						// - The rootChanged event will already be raised at the end of the current upgrade
 						// - It doesn't matter that `lastRoot` isn't updated in this case, because `update` will be called again before the upgrade
 						//   completes (at which point this callback and the `lastRoot` captured here will be out of scope anyway)
-						if (!this.midUpgrade && lastRoot !== this.root) {
-							lastRoot = this.root;
+						if (!this.midUpgrade && lastRoot !== this.flexRoot.content) {
+							lastRoot = this.flexRoot.content;
 							this.events.emit("rootChanged");
 						}
 					}),
@@ -374,6 +406,10 @@ export class SchematizingSimpleTreeView<
 		);
 
 		if (!this.midUpgrade) {
+			assert(
+				this.pendingHydration === undefined,
+				"no nodes should be pending hydration when triggering events that could access nodes",
+			);
 			this.events.emit("schemaChanged");
 			this.events.emit("rootChanged");
 		}
@@ -386,6 +422,9 @@ export class SchematizingSimpleTreeView<
 		} finally {
 			this.midUpgrade = false;
 		}
+		// Ensure hydration is flushed before events run which could access nodes.
+		this.pendingHydration?.();
+		this.pendingHydration = undefined;
 		this.events.emit("schemaChanged");
 		this.events.emit("rootChanged");
 	}
@@ -426,7 +465,7 @@ export class SchematizingSimpleTreeView<
 		}
 	}
 
-	public get root(): ReadableField<TRootSchema> {
+	private get flexRoot(): FlexTreeOptionalField | FlexTreeRequiredField {
 		this.breaker.use();
 		if (!this.compatibility.canView) {
 			throw new UsageError(
@@ -434,7 +473,17 @@ export class SchematizingSimpleTreeView<
 			);
 		}
 		const view = this.getFlexTreeContext();
-		return tryGetTreeNodeForField(view.root) as ReadableField<TRootSchema>;
+		assert(
+			view.root.is(FieldKinds.optional) ||
+				view.root.is(FieldKinds.required) ||
+				view.root.is(FieldKinds.identifier),
+			"unexpected root field kind",
+		);
+		return view.root;
+	}
+
+	public get root(): ReadableField<TRootSchema> {
+		return tryGetTreeNodeForField(this.flexRoot) as ReadableField<TRootSchema>;
 	}
 
 	public set root(newRoot: InsertableField<TRootSchema>) {
@@ -499,7 +548,7 @@ export function addConstraintsToTransaction(
 	for (const constraint of constraints) {
 		switch (constraint.type) {
 			case "nodeInDocument": {
-				const node = getOrCreateInnerNode(constraint.node);
+				const node = getInnerNode(constraint.node);
 				const nodeStatus = getKernel(constraint.node).getStatus();
 				if (nodeStatus !== TreeStatus.InDocument) {
 					const revertText = constraintsOnRevert ? " on revert" : "";

package/src/shared-tree/sharedTree.ts

@@ -38,7 +38,6 @@ import {
 	type SchemaFormatVersion,
 	SchemaVersion,
 	type TreeFieldStoredSchema,
-	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
 	type TreeStoredSchema,
 	TreeStoredSchemaRepository,
@@ -55,6 +54,7 @@ import {
 	TreeCompressionStrategy,
 	buildChunkedForest,
 	buildForest,
+	defaultIncrementalEncodingPolicy,
 	defaultSchemaPolicy,
 	getCodecTreeForFieldBatchFormat,
 	getCodecTreeForForestFormat,
@@ -64,6 +64,7 @@ import {
 	makeMitigatedChangeFamily,
 	makeSchemaCodec,
 	makeTreeChunker,
+	type IncrementalEncodingPolicy,
 	type FieldBatchFormatVersion,
 	type ForestFormatVersion,
 	type TreeCompressionStrategyPrivate,
@@ -305,7 +306,13 @@ export class SharedTreeKernel
 		const options = { ...defaultSharedTreeOptions, ...optionsParam };
 		const codecVersions = getCodecVersions(options.formatVersion);
 		const schema = new TreeStoredSchemaRepository();
-		const forest = buildConfiguredForest(breaker, options.forest, schema, idCompressor);
+		const forest = buildConfiguredForest(
+			breaker,
+			options.forest,
+			schema,
+			idCompressor,
+			options.shouldEncodeIncrementally,
+		);
 		const revisionTagCodec = new RevisionTagCodec(idCompressor);
 		const removedRoots = makeDetachedFieldIndex(
 			"repair",
@@ -339,7 +346,7 @@ export class SharedTreeKernel
 			encoderContext,
 			options,
 			idCompressor,
-			options.shouldEncodeFieldIncrementally,
+			options.shouldEncodeIncrementally,
 		);
 		const removedRootsSummarizer = new DetachedFieldIndexSummarizer(removedRoots);
 		const innerChangeFamily = new SharedTreeChangeFamily(
@@ -794,16 +801,11 @@ export interface SharedTreeOptionsInternal
 		Partial<SharedTreeFormatOptionsInternal> {
 	disposeForksAfterTransaction?: boolean;
 	/**
-	 * Returns whether a field should be incrementally encoded.
-	 * @param nodeIdentifier - The identifier of the node containing the field.
-	 * @param fieldKey - The key of the field to check.
+	 * Returns whether a node / field should be incrementally encoded.
 	 * @remarks
-	 * The policy for which fields should get incremental encoding should eventually be specified some other way.
+	 * See {@link IncrementalEncodingPolicy}.
 	 */
-	shouldEncodeFieldIncrementally?(
-		nodeIdentifier: TreeNodeSchemaIdentifier,
-		fieldKey: FieldKey,
-	): boolean;
+	shouldEncodeIncrementally?: IncrementalEncodingPolicy;
 }
 /**
  * Configuration options for SharedTree's internal tree storage.
@@ -882,8 +884,17 @@ export const ForestTypeReference = toForestType(
  * @beta
  */
 export const ForestTypeOptimized = toForestType(
-	(breaker: Breakable, schema: TreeStoredSchemaSubscription, idCompressor: IIdCompressor) =>
-		buildChunkedForest(makeTreeChunker(schema, defaultSchemaPolicy), undefined, idCompressor),
+	(
+		breaker: Breakable,
+		schema: TreeStoredSchemaSubscription,
+		idCompressor: IIdCompressor,
+		shouldEncodeIncrementally: IncrementalEncodingPolicy,
+	) =>
+		buildChunkedForest(
+			makeTreeChunker(schema, defaultSchemaPolicy, shouldEncodeIncrementally),
+			undefined,
+			idCompressor,
+		),
 );
 
 /**
@@ -904,6 +915,7 @@ type ForestFactory = (
 	breaker: Breakable,
 	schema: TreeStoredSchemaSubscription,
 	idCompressor: IIdCompressor,
+	shouldEncodeIncrementally: IncrementalEncodingPolicy,
 ) => IEditableForest;
 
 function toForestType(factory: ForestFactory): ForestType {
@@ -918,8 +930,14 @@ export function buildConfiguredForest(
 	factory: ForestType,
 	schema: TreeStoredSchemaSubscription,
 	idCompressor: IIdCompressor,
+	shouldEncodeIncrementally: IncrementalEncodingPolicy,
 ): IEditableForest {
-	return (factory as unknown as ForestFactory)(breaker, schema, idCompressor);
+	return (factory as unknown as ForestFactory)(
+		breaker,
+		schema,
+		idCompressor,
+		shouldEncodeIncrementally,
+	);
 }
 
 export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
@@ -929,12 +947,7 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	treeEncodeType: TreeCompressionStrategy.Compressed,
 	formatVersion: SharedTreeFormatVersion.v3,
 	disposeForksAfterTransaction: true,
-	shouldEncodeFieldIncrementally: (
-		nodeIdentifier: TreeNodeSchemaIdentifier,
-		fieldKey: FieldKey,
-	): boolean => {
-		return false;
-	},
+	shouldEncodeIncrementally: defaultIncrementalEncodingPolicy,
 };
 
 function exportSimpleFieldSchemaStored(schema: TreeFieldStoredSchema): SimpleFieldSchema {

package/src/shared-tree/tree.ts

@@ -11,7 +11,7 @@ import {
 	type TreeNode,
 	type TreeNodeApi,
 	type TreeView,
-	getOrCreateInnerNode,
+	getInnerNode,
 	treeNodeApi,
 	rollback,
 	type TransactionConstraint,
@@ -447,7 +447,7 @@ export function runTransaction<
 	} else {
 		const node = treeOrNode as TNode;
 		const t = transaction as (node: TNode) => TResult | typeof rollback;
-		const context = getOrCreateInnerNode(node).context;
+		const context = getInnerNode(node).context;
 		if (context.isHydrated() === false) {
 			throw new UsageError(
 				"Transactions cannot be run on Unhydrated nodes. Transactions apply to a TreeView and Unhydrated nodes are not part of a TreeView.",

package/src/shared-tree/treeAlpha.ts

@@ -44,7 +44,7 @@ import {
 	unhydratedFlexTreeFromInsertable,
 	getOrCreateNodeFromInnerNode,
 	getOrCreateNodeFromInnerUnboxedNode,
-	getOrCreateInnerNode,
+	getInnerNode,
 	NodeKind,
 	tryGetTreeNodeForField,
 	isObjectNodeSchema,
@@ -881,7 +881,7 @@ export const TreeAlpha: TreeAlpha = {
 		node: TreeNode,
 		propertyKey: string | number,
 	): TreeNode | TreeLeafValue | undefined => {
-		const flexNode = getOrCreateInnerNode(node);
+		const flexNode = getInnerNode(node);
 		debugAssert(
 			() => !flexNode.context.isDisposed() || "The provided tree node has been disposed.",
 		);
@@ -951,7 +951,7 @@ export const TreeAlpha: TreeAlpha = {
 	},
 
 	children(node: TreeNode): [propertyKey: string | number, child: TreeNode | TreeLeafValue][] {
-		const flexNode = getOrCreateInnerNode(node);
+		const flexNode = getInnerNode(node);
 		debugAssert(
 			() => !flexNode.context.isDisposed() || "The provided tree node has been disposed.",
 		);

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

@@ -90,6 +90,13 @@ export type {
 	MapNodeCustomizableSchemaUnsafe,
 	System_Unsafe,
 	TreeRecordNodeUnsafe,
+	UnannotateAllowedTypeUnsafe,
+	AnnotatedAllowedTypeUnsafe,
+	AnnotatedAllowedTypesUnsafe,
+	AllowedTypesFullUnsafe,
+	AllowedTypesFullFromMixedUnsafe,
+	UnannotateAllowedTypesListUnsafe,
+	AnnotateAllowedTypesListUnsafe,
 } from "./typesUnsafe.js";
 
 export {

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

@@ -40,10 +40,14 @@ import {
 	AnnotatedAllowedTypesInternal,
 } from "../core/index.js";
 import type {
+	AllowedTypesFullFromMixedUnsafe,
+	AnnotatedAllowedTypeUnsafe,
 	ArrayNodeCustomizableSchemaUnsafe,
 	MapNodeCustomizableSchemaUnsafe,
 	System_Unsafe,
 	TreeRecordNodeUnsafe,
+	UnannotateAllowedTypeUnsafe,
+	Unenforced,
 } from "./typesUnsafe.js";
 import type { SimpleObjectNodeSchema } from "../simpleSchema.js";
 import { SchemaFactoryBeta } from "./schemaFactoryBeta.js";
@@ -113,28 +117,64 @@ export interface SchemaStaticsAlpha {
 		t: T,
 		metadata?: AllowedTypesMetadata,
 	) => AllowedTypesFullFromMixed<T>;
+
+	/**
+	 * {@link SchemaStaticsAlpha.staged} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStaticsAlpha.staged} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 */
+	stagedRecursive: <
+		const T extends Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>,
+	>(
+		t: T,
+	) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>;
+
+	/**
+	 * {@link SchemaStaticsAlpha.types} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStaticsAlpha.types} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 * @privateRemarks
+	 * If all inputs (at least recursive ones) were required to be annotated, this could be typed more strongly.
+	 * In that case it could use `T extends readonly (AnnotatedAllowedTypeUnsafe | LazyItem<System_Unsafe.TreeNodeSchemaUnsafe>)[]`.
+	 */
+	readonly typesRecursive: <
+		const T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[],
+	>(
+		t: T,
+		metadata?: AllowedTypesMetadata,
+	) => AllowedTypesFullFromMixedUnsafe<T>;
 }
 
+const staged = <const T extends LazyItem<TreeNodeSchema>>(
+	t: T | AnnotatedAllowedType<T>,
+): AnnotatedAllowedType<T> => {
+	const annotatedType = normalizeToAnnotatedAllowedType(t);
+	return {
+		type: annotatedType.type,
+		metadata: {
+			...annotatedType.metadata,
+			stagedSchemaUpgrade: createSchemaUpgrade(),
+		},
+	};
+};
+
+const types = <const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]>(
+	t: T,
+	metadata: AllowedTypesMetadata = {},
+): AllowedTypesFullFromMixed<T> => {
+	return AnnotatedAllowedTypesInternal.createMixed<T>(t, metadata);
+};
+
 const schemaStaticsAlpha: SchemaStaticsAlpha = {
-	staged: <const T extends LazyItem<TreeNodeSchema>>(
-		t: T | AnnotatedAllowedType<T>,
-	): AnnotatedAllowedType<T> => {
-		const annotatedType = normalizeToAnnotatedAllowedType(t);
-		return {
-			type: annotatedType.type,
-			metadata: {
-				...annotatedType.metadata,
-				stagedSchemaUpgrade: createSchemaUpgrade(),
-			},
-		};
-	},
+	staged,
+	types,
 
-	types: <const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]>(
-		t: T,
-		metadata: AllowedTypesMetadata = {},
-	): AllowedTypesFullFromMixed<T> => {
-		return AnnotatedAllowedTypesInternal.createMixed<T>(t, metadata);
-	},
+	stagedRecursive: staged as SchemaStaticsAlpha["stagedRecursive"],
+	typesRecursive: types as unknown as SchemaStaticsAlpha["typesRecursive"],
 };
 
 /**
@@ -310,6 +350,16 @@ export class SchemaFactoryAlpha<
 	 */
 	public staged = schemaStaticsAlpha.staged;
 
+	/**
+	 * {@inheritDoc SchemaStaticsAlpha.stagedRecursive}
+	 */
+	public static stagedRecursive = schemaStaticsAlpha.stagedRecursive;
+
+	/**
+	 * {@inheritDoc SchemaStaticsAlpha.stagedRecursive}
+	 */
+	public stagedRecursive = schemaStaticsAlpha.stagedRecursive;
+
 	/**
 	 * {@inheritDoc SchemaStaticsAlpha.types}
 	 */
@@ -320,6 +370,16 @@ export class SchemaFactoryAlpha<
 	 */
 	public types = schemaStaticsAlpha.types;
 
+	/**
+	 * {@inheritDoc SchemaStaticsAlpha.typesRecursive}
+	 */
+	public static typesRecursive = schemaStaticsAlpha.typesRecursive;
+
+	/**
+	 * {@inheritDoc SchemaStaticsAlpha.typesRecursive}
+	 */
+	public typesRecursive = schemaStaticsAlpha.typesRecursive;
+
 	/**
 	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
 	 *
@@ -405,7 +465,7 @@ export class SchemaFactoryAlpha<
 	}
 
 	/**
-	 * {@inheritDoc SchemaFactory.objectRecursive}
+	 * {@link SchemaFactory.arrayRecursive} but with support for some alpha features.
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	public override arrayRecursive<

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

@@ -228,6 +228,9 @@ export const schemaStatics = {
 	},
 } as const;
 
+/**
+ * {@link Unenforced} version of {@link createFieldSchema}.
+ */
 function createFieldSchemaUnsafe<
 	Kind extends FieldKind,
 	Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,