@fluidframework/tree 2.52.0 → 2.53.0-350190

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

@@ -5,6 +5,7 @@
 
 import {
 	normalizeAnnotatedAllowedTypes,
+	type AnnotatedAllowedType,
 	type NormalizedAnnotatedAllowedTypes,
 } from "./allowedTypes.js";
 import { getTreeNodeSchemaPrivateData, type TreeNodeSchema } from "./treeNodeSchema.js";
@@ -50,26 +51,42 @@ export function walkAllowedTypes(
 	visitor: SchemaVisitor,
 	visitedSet: Set<TreeNodeSchema> = new Set(),
 ): void {
-	for (const { type } of annotatedAllowedTypes.types) {
-		walkNodeSchema(type, visitor, visitedSet);
+	for (const allowedType of annotatedAllowedTypes.types) {
+		if ((visitor.allowedTypeFilter ?? (() => true))(allowedType)) {
+			walkNodeSchema(allowedType.type, visitor, visitedSet);
+		}
 	}
 	visitor.allowedTypes?.(annotatedAllowedTypes);
 }
 
 /**
- * Callbacks for use in {@link walkFieldSchema} / {@link walkAllowedTypes} / {@link walkNodeSchema}.
+ * Callbacks and options for use in {@link walkFieldSchema} / {@link walkAllowedTypes} / {@link walkNodeSchema}.
  * @internal
  */
 export interface SchemaVisitor {
 	/**
-	 * Called once for each node schema.
+	 * Called once for each node schema reached.
 	 */
 	node?: (schema: TreeNodeSchema) => void;
 	/**
 	 * Called once for each set of allowed types.
-	 * Includes implicit allowed types (when a single type was used instead of an array).
+	 * @remarks
+	 * This includes every field, as well as the allowed types for maps and arrays nodes and the root if starting at {@link walkAllowedTypes}.
 	 *
-	 * This includes every field, but also the allowed types array for maps and arrays and the root if starting at {@link walkAllowedTypes}.
+	 * Each allowed types in the schema is visited as it was in the original schema except for normalization.
+	 *
+	 * After this is called {@link SchemaVisitor.allowedTypeFilter} is applied to each allowed type in the schema to determine which of them are walked into.
 	 */
 	allowedTypes?: (allowedTypes: NormalizedAnnotatedAllowedTypes) => void;
+	/**
+	 * If true, will walk into this `allowedType`.
+	 * If false, the `allowedType` will not be walked into.
+	 *
+	 * If not provided, all allowedTypes will be walked into.
+	 * @remarks
+	 * Called after {@link SchemaVisitor.allowedTypes}.
+	 * @privateRemarks
+	 * It would be possible to combine this with `allowedTypes` into a single callback, but for the current usage this separation is more convenient.
+	 */
+	allowedTypeFilter?: (allowedType: AnnotatedAllowedType<TreeNodeSchema>) => boolean;
 }

package/src/simple-tree/createContext.ts

@@ -15,7 +15,7 @@ import {
 	type TreeNodeSchemaInitializedData,
 } from "./core/index.js";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "./fieldSchema.js";
-import { toStoredSchema } from "./toStoredSchema.js";
+import { toStoredSchema, toUnhydratedSchema } from "./toStoredSchema.js";
 
 const contextCache: WeakMap<ImplicitFieldSchema, Context> = new WeakMap();
 
@@ -28,7 +28,10 @@ export function getUnhydratedContext(schema: ImplicitFieldSchema): Context {
 	return getOrCreate(contextCache, schema, (s) => {
 		const normalized = normalizeFieldSchema(schema);
 
-		const flexContext = new UnhydratedContext(defaultSchemaPolicy, toStoredSchema(schema));
+		const flexContext = new UnhydratedContext(
+			defaultSchemaPolicy,
+			toStoredSchema(schema, toUnhydratedSchema),
+		);
 		return new Context(
 			flexContext,
 			Context.schemaMapFromRootSchema(normalized.annotatedAllowedTypesNormalized),

package/src/simple-tree/fieldSchema.ts

@@ -468,7 +468,8 @@ export class FieldSchemaAlpha<
 			normalizeAnnotatedAllowedTypes(annotatedAllowedTypes),
 		);
 		this.lazyIdentifiers = new Lazy(
-			() => new Set([...this.allowedTypeSet].map((t) => t.identifier)),
+			() =>
+				new Set(this.annotatedAllowedTypesNormalized.types.map(({ type }) => type.identifier)),
 		);
 		this.propsAlpha = props;
 	}

package/src/simple-tree/index.ts

@@ -47,9 +47,9 @@ export {
 	type UnannotateAllowedTypes,
 	type UnannotateAllowedType,
 	type UnannotateAllowedTypesList,
-	type UnannotateAllowedTypeOrLazyItem,
 	type AllowedTypeMetadata,
 	type AnnotatedAllowedTypes,
+	type SchemaUpgrade,
 	type LazyItem,
 	type FlexList,
 	type FlexListToUnion,
@@ -57,6 +57,7 @@ export {
 	walkNodeSchema,
 	walkAllowedTypes,
 	type SchemaVisitor,
+	type SimpleNodeSchemaBase,
 } from "./core/index.js";
 export { walkFieldSchema } from "./walkFieldSchema.js";
 export type { UnsafeUnknownSchema, Insertable } from "./unsafeUnknownSchema.js";
@@ -161,6 +162,7 @@ export {
 	type TreeChangeEvents,
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
+	type SchemaStaticsAlpha,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,
@@ -170,7 +172,6 @@ export type {
 	SimpleMapNodeSchema,
 	SimpleArrayNodeSchema,
 	SimpleObjectNodeSchema,
-	SimpleNodeSchemaBase,
 	SimpleNodeSchemaBaseAlpha,
 	SimpleObjectFieldSchema,
 	SimpleRecordNodeSchema,
@@ -240,7 +241,17 @@ export {
 	prepareForInsertion,
 	prepareForInsertionContextless,
 } from "./prepareForInsertion.js";
-export { toStoredSchema, getStoredSchema, convertFieldKind } from "./toStoredSchema.js";
+export {
+	toStoredSchema,
+	getStoredSchema,
+	convertFieldKind,
+	toUpgradeSchema,
+	toInitialSchema,
+	convertField,
+	toUnhydratedSchema,
+	restrictiveStoredSchemaGenerationOptions,
+	permissiveStoredSchemaGenerationOptions,
+} from "./toStoredSchema.js";
 export {
 	numberSchema,
 	stringSchema,

package/src/simple-tree/leafNodeSchema.ts

@@ -7,7 +7,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
-import { type TreeValue, ValueSchema } from "../core/index.js";
+import { LeafNodeStoredSchema, type TreeValue, ValueSchema } from "../core/index.js";
 import {
 	type FlexTreeNode,
 	isFlexTreeNode,
@@ -64,6 +64,7 @@ export class LeafNodeSchema<Name extends string, const T extends ValueSchema>
 				): FlexContent => leafToFlexContent(data, this, allowedTypes),
 			})),
 		childAnnotatedAllowedTypes: [],
+		toStored: () => new LeafNodeStoredSchema(this.leafKind),
 	};
 	#initializedData: TreeNodeSchemaInitializedData | undefined;
 

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { Lazy, oob, fail } from "@fluidframework/core-utils/internal";
+import { Lazy, oob, fail, assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { EmptyKey } from "../../../core/index.js";
+import { EmptyKey, ObjectNodeStoredSchema } from "../../../core/index.js";
 import type {
 	FlexibleFieldContent,
 	FlexTreeNode,
@@ -48,6 +48,7 @@ import {
 	createTreeNodeSchemaPrivateData,
 	type FlexContent,
 	type TreeNodeSchemaPrivateData,
+	convertAllowedTypes,
 } from "../../core/index.js";
 import {
 	type FactoryContent,
@@ -68,6 +69,7 @@ import type {
 } from "./arrayNodeTypes.js";
 import { brand, type JsonCompatibleReadOnlyObject } from "../../../util/index.js";
 import { nullSchema } from "../../leafNodeSchema.js";
+import { arrayNodeStoredSchema } from "../../toStoredSchema.js";
 
 /**
  * A covariant base type for {@link (TreeArrayNode:interface)}.
@@ -888,10 +890,21 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAnnotatedAllowedTypes
 		const contentArray = content.flatMap((c): InsertableContent[] =>
 			c instanceof IterableTreeArrayContent ? Array.from(c) : [c],
 		);
+
+		const kernel = getKernel(this);
+		const flexContext = kernel.getOrCreateInnerNode().context;
+		assert(flexContext === kernel.context.flexContext, "Expected flexContext to match");
+		const innerSchema = kernel.context.flexContext.schema.nodeSchema.get(
+			brand(kernel.schema.identifier),
+		);
+		assert(innerSchema instanceof ObjectNodeStoredSchema, "Expected ObjectNodeStoredSchema");
+		const fieldSchema = innerSchema.getFieldSchema(EmptyKey);
+
 		const mapTrees = prepareArrayContentForInsertion(
 			contentArray,
 			this.simpleSchema,
 			sequenceField.context,
+			fieldSchema.types,
 		);
 
 		return mapTrees;
@@ -1029,6 +1042,11 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAnnotatedAllowedTypes
 	): void {
 		const destinationField = getSequenceField(this);
 		const destinationSchema = this.allowedTypes;
+		const kernel = getKernel(this);
+		const destinationStored = (
+			kernel.context.flexContext.schema.nodeSchema.get(brand(kernel.schema.identifier)) ??
+			fail("missing schema for array node")
+		).getFieldSchema(EmptyKey).types;
 		const sourceField = source !== undefined ? getSequenceField(source) : destinationField;
 
 		validateIndex(destinationGap, destinationField, "moveRangeToIndex", true);
@@ -1040,7 +1058,15 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAnnotatedAllowedTypes
 				const sourceNode = sourceField.boxedAt(i) ?? oob();
 				const sourceSchema = getSimpleNodeSchemaFromInnerNode(sourceNode);
 				if (!destinationSchema.has(sourceSchema)) {
-					throw new UsageError("Type in source sequence is not allowed in destination.");
+					throw new UsageError(
+						`Type ${sourceNode.type} in source sequence is not allowed in destination.`,
+					);
+				}
+				if (!destinationStored.has(sourceNode.type)) {
+					// TODO: better and centralized messages for missing staged schema updates.
+					throw new UsageError(
+						`Type ${sourceNode.type} in source sequence is not allowed in destination's stored schema: this would likely require upgrading the document to permit a staged schema.`,
+					);
 				}
 			}
 		}
@@ -1250,7 +1276,9 @@ export function arraySchema<
 		}
 
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
-			return (privateData ??= createTreeNodeSchemaPrivateData(this, [info]));
+			return (privateData ??= createTreeNodeSchemaPrivateData(this, [info], (storedOptions) =>
+				arrayNodeStoredSchema(convertAllowedTypes(info, storedOptions), persistedMetadata),
+			));
 		}
 	}
 

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -3,10 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { Lazy } from "@fluidframework/core-utils/internal";
+import { assert, Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
+	FieldKinds,
 	isTreeValue,
 	type FlexibleNodeContent,
 	type FlexTreeNode,
@@ -44,6 +45,7 @@ import {
 	createTreeNodeSchemaPrivateData,
 	type FlexContent,
 	type TreeNodeSchemaPrivateData,
+	convertAllowedTypes,
 } from "../../core/index.js";
 import {
 	unhydratedFlexTreeFromInsertable,
@@ -65,6 +67,7 @@ import type {
 	MapNodeSchema,
 } from "./mapNodeTypes.js";
 import { recordLikeDataToFlexContent } from "../common.js";
+import { MapNodeStoredSchema } from "../../../core/index.js";
 
 /**
  * A map of string keys to tree objects.
@@ -209,10 +212,16 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 	public set(key: string, value: InsertableTreeNodeFromImplicitAllowedTypes<T>): this {
 		const kernel = getKernel(this);
 		const node = this.innerNode;
+		const innerSchema = this.innerNode.context.schema.nodeSchema.get(
+			brand(kernel.schema.identifier),
+		);
+		assert(innerSchema instanceof MapNodeStoredSchema, "Expected MapNodeStoredSchema");
+
 		const mapTree = prepareForInsertion(
 			value as InsertableContent | undefined,
 			createFieldSchema(FieldKind.Optional, kernel.schema.info as ImplicitAllowedTypes),
 			node.context,
+			innerSchema.mapFields,
 		);
 
 		const field = node.getBoxed(brand(key));
@@ -328,7 +337,19 @@ export function mapSchema<
 		}
 
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
-			return (privateData ??= createTreeNodeSchemaPrivateData(this, [info]));
+			return (privateData ??= createTreeNodeSchemaPrivateData(
+				this,
+				[info],
+				(storedOptions) =>
+					new MapNodeStoredSchema(
+						{
+							kind: FieldKinds.optional.identifier,
+							types: convertAllowedTypes(info, storedOptions),
+							persistedMetadata,
+						},
+						persistedMetadata,
+					),
+			));
 		}
 	}
 	const schemaErased: MapNodeCustomizableSchema<

package/src/simple-tree/node-kinds/object/objectNode.ts

@@ -7,7 +7,11 @@ import { assert, Lazy, fail, debugAssert } from "@fluidframework/core-utils/inte
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
-import type { FieldKey } from "../../../core/index.js";
+import {
+	ObjectNodeStoredSchema,
+	type FieldKey,
+	type TreeFieldStoredSchema,
+} from "../../../core/index.js";
 import {
 	FieldKinds,
 	isTreeValue,
@@ -86,7 +90,7 @@ import {
 	type FactoryContentObject,
 	type InsertableContent,
 } from "../../unhydratedFlexTreeFromInsertable.js";
-import { convertFieldKind } from "../../toStoredSchema.js";
+import { convertField, convertFieldKind } from "../../toStoredSchema.js";
 
 /**
  * Generates the properties for an ObjectNode from its field schema object.
@@ -288,10 +292,16 @@ function createProxyHandler(
 					: false;
 			}
 
+			const innerNode = getOrCreateInnerNode(proxy);
+
+			const innerSchema = innerNode.context.schema.nodeSchema.get(brand(schema.identifier));
+			assert(innerSchema instanceof ObjectNodeStoredSchema, "Expected ObjectNodeStoredSchema");
+
 			setField(
-				getOrCreateInnerNode(proxy).getBoxed(fieldInfo.storedKey),
+				innerNode.getBoxed(fieldInfo.storedKey),
 				fieldInfo.schema,
 				value,
+				innerSchema.getFieldSchema(fieldInfo.storedKey),
 			);
 			return true;
 		},
@@ -348,8 +358,14 @@ export function setField(
 	field: FlexTreeField,
 	simpleFieldSchema: FieldSchema,
 	value: InsertableContent | undefined,
+	destinationSchema: TreeFieldStoredSchema,
 ): void {
-	const mapTree = prepareForInsertion(value, simpleFieldSchema, field.context);
+	const mapTree = prepareForInsertion(
+		value,
+		simpleFieldSchema,
+		field.context,
+		destinationSchema,
+	);
 
 	switch (field.schema) {
 		case FieldKinds.required.identifier: {
@@ -585,6 +601,20 @@ export function objectSchema<
 					flexKeyMap.values(),
 					({ schema }) => normalizeFieldSchema(schema).annotatedAllowedTypes,
 				),
+				(storedOptions) => {
+					const fields: Map<FieldKey, TreeFieldStoredSchema> = new Map();
+					for (const fieldSchema of flexKeyMap.values()) {
+						assert(
+							fieldSchema.schema instanceof FieldSchemaAlpha,
+							"Expected FieldSchemaAlpha",
+						);
+						fields.set(
+							brand(fieldSchema.storedKey),
+							convertField(fieldSchema.schema, storedOptions),
+						);
+					}
+					return new ObjectNodeStoredSchema(fields, persistedMetadata);
+				},
 			));
 		}
 	}

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { Lazy } from "@fluidframework/core-utils/internal";
+import { assert, Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { type JsonCompatibleReadOnlyObject, brand } from "../../../util/index.js";
@@ -34,6 +34,7 @@ import {
 	type FlexContent,
 	CompatibilityLevel,
 	type TreeNodeSchemaPrivateData,
+	convertAllowedTypes,
 } from "../../core/index.js";
 import { getTreeNodeSchemaInitializedData } from "../../createContext.js";
 import { tryGetTreeNodeForField } from "../../getTreeNodeForField.js";
@@ -51,12 +52,14 @@ import type {
 	TreeRecordNode,
 } from "./recordNodeTypes.js";
 import {
+	FieldKinds,
 	isTreeValue,
 	type FlexTreeNode,
 	type FlexTreeOptionalField,
 } from "../../../feature-libraries/index.js";
 import { prepareForInsertion } from "../../prepareForInsertion.js";
 import { recordLikeDataToFlexContent } from "../common.js";
+import { MapNodeStoredSchema } from "../../../core/index.js";
 
 /**
  * Create a proxy which implements the {@link TreeRecordNode} API.
@@ -122,11 +125,14 @@ function createRecordNodeProxy(
 			const innerNode = getOrCreateInnerNode(receiver);
 			const field = innerNode.getBoxed(brand(key)) as FlexTreeOptionalField;
 			const kernel = getKernel(receiver);
+			const innerSchema = innerNode.context.schema.nodeSchema.get(brand(schema.identifier));
+			assert(innerSchema instanceof MapNodeStoredSchema, "Expected MapNodeStoredSchema");
 
 			const mapTree = prepareForInsertion(
 				value,
 				createFieldSchema(FieldKind.Optional, kernel.schema.info as ImplicitAllowedTypes),
 				innerNode.context,
+				innerSchema.mapFields,
 			);
 
 			field.editor.set(mapTree, field.length === 0);
@@ -390,7 +396,19 @@ export function recordSchema<
 		}
 
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
-			return (privateData ??= createTreeNodeSchemaPrivateData(this, [info]));
+			return (privateData ??= createTreeNodeSchemaPrivateData(
+				this,
+				[info],
+				(storedOptions) =>
+					new MapNodeStoredSchema(
+						{
+							kind: FieldKinds.optional.identifier,
+							types: convertAllowedTypes(info, storedOptions),
+							persistedMetadata,
+						},
+						persistedMetadata,
+					),
+			));
 		}
 	}
 

package/src/simple-tree/prepareForInsertion.ts

@@ -11,6 +11,7 @@ import type {
 	FieldKey,
 	DetachedField,
 	TreeFieldStoredSchema,
+	TreeTypeSet,
 } from "../core/index.js";
 import {
 	type FlexTreeContext,
@@ -21,7 +22,7 @@ import {
 	type FlexibleNodeContent,
 	throwOutOfSchema,
 } from "../feature-libraries/index.js";
-import { normalizeFieldSchema, type ImplicitAnnotatedFieldSchema } from "./fieldSchema.js";
+import type { ImplicitAnnotatedFieldSchema } from "./fieldSchema.js";
 import {
 	type InsertableContent,
 	unhydratedFlexTreeFromInsertable,
@@ -36,7 +37,6 @@ import {
 } from "./core/index.js";
 import { debugAssert, oob } from "@fluidframework/core-utils/internal";
 import { isFieldInSchema } from "../feature-libraries/index.js";
-import { convertField } from "./toStoredSchema.js";
 
 /**
  * For now, schema validation for inserted content is always enabled.
@@ -58,12 +58,14 @@ export function prepareForInsertion<TIn extends InsertableContent | undefined>(
 	data: TIn,
 	schema: ImplicitAnnotatedFieldSchema,
 	destinationContext: FlexTreeContext,
+	destinationSchema: TreeFieldStoredSchema,
 ): TIn extends undefined ? undefined : FlexibleNodeContent {
 	return prepareForInsertionContextless(
 		data,
 		schema,
 		getSchemaAndPolicy(destinationContext),
 		destinationContext.isHydrated() ? destinationContext : undefined,
+		destinationSchema,
 	);
 }
 
@@ -84,19 +86,18 @@ export function prepareArrayContentForInsertion(
 	data: readonly InsertableContent[],
 	schema: ImplicitAnnotatedAllowedTypes,
 	destinationContext: FlexTreeContext,
+	destinationSchema: TreeTypeSet,
 ): FlexibleFieldContent {
 	const mapTrees: UnhydratedFlexTreeNode[] = data.map((item) =>
 		unhydratedFlexTreeFromInsertable(item, schema),
 	);
 
-	const fieldSchema = convertField(normalizeFieldSchema(schema));
-
 	validateAndPrepare(
 		getSchemaAndPolicy(destinationContext),
 		destinationContext.isHydrated() ? destinationContext : undefined,
 		{
 			kind: FieldKinds.sequence.identifier,
-			types: fieldSchema.types,
+			types: destinationSchema,
 			persistedMetadata: undefined,
 		},
 		mapTrees,
@@ -119,12 +120,12 @@ export function prepareForInsertionContextless<TIn extends InsertableContent | u
 	schema: ImplicitAnnotatedFieldSchema,
 	schemaAndPolicy: SchemaAndPolicy,
 	hydratedData: FlexTreeHydratedContextMinimal | undefined,
+	destinationSchema: TreeFieldStoredSchema,
 ): TIn extends undefined ? undefined : FlexibleNodeContent {
 	const mapTree = unhydratedFlexTreeFromInsertable(data, schema);
 
 	const contentArray = mapTree === undefined ? [] : [mapTree];
-	const fieldSchema = convertField(normalizeFieldSchema(schema));
-	validateAndPrepare(schemaAndPolicy, hydratedData, fieldSchema, contentArray);
+	validateAndPrepare(schemaAndPolicy, hydratedData, destinationSchema, contentArray);
 
 	return mapTree;
 }
@@ -146,6 +147,10 @@ function validateAndPrepare(
 		// This ensures that when `isFieldInSchema` requests identifiers (or any other contextual defaults),
 		// they were already creating used the more specific context we have access to from `hydratedData`.
 		prepareContentForHydration(mapTrees, hydratedData.checkout.forest, hydratedData);
+		// TODO: AB#45723
+		// Now that staged schema rely on this validation, its a bit odd we don't do it for insertion into unhydrated contexts.
+		// We can't simply enable it for them however due to contextual default fields which would not have been created yet (see comment above).
+		// Specifically at least clone can result in unhydrated trees which can end up violating their stored schema (but not view schema) just using the type safe APIs.
 		if (validateSchema === true) {
 			isFieldInSchema(mapTrees, fieldSchema, schemaAndPolicy, throwOutOfSchema);
 		}

package/src/simple-tree/simpleSchema.ts

@@ -5,7 +5,7 @@
 
 import type { ValueSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
-import type { NodeKind, NodeSchemaMetadata } from "./core/index.js";
+import type { NodeKind, SimpleNodeSchemaBase } from "./core/index.js";
 import type { FieldKind, FieldSchemaMetadata } from "./fieldSchema.js";
 
 /*
@@ -13,30 +13,6 @@ import type { FieldKind, FieldSchemaMetadata } from "./fieldSchema.js";
  * - Customize their JSON serialization to use these formats or provide some other serialization scheme.
  */
 
-/**
- * Base interface for {@link TreeNodeSchema} and {@link SimpleNodeSchema} types.
- * Once simple schema is stable this doesn't have a reason to be kept `@system`, but it could be.
- * @system
- * @public
- * @sealed
- */
-export interface SimpleNodeSchemaBase<
-	out TNodeKind extends NodeKind,
-	out TCustomMetadata = unknown,
-> {
-	/**
-	 * The {@link NodeKind}.
-	 *
-	 * @remarks can be used to type-switch between implementations.
-	 */
-	readonly kind: TNodeKind;
-
-	/**
-	 * User-provided {@link NodeSchemaMetadata} for this schema.
-	 */
-	readonly metadata: NodeSchemaMetadata<TCustomMetadata>;
-}
-
 /**
  * A {@link SimpleNodeSchema} containing fields for alpha features.
  *
@@ -230,7 +206,11 @@ export interface SimpleTreeSchema {
 	/**
 	 * The complete set of node schema definitions recursively referenced by the tree's {@link SimpleTreeSchema.root}.
 	 *
-	 * @remarks the keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
+	 * @remarks
+	 * The keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
+	 *
+	 * Information about if a schema is {@link SchemaStaticsAlpha.staged | staged} or not is not available as the "Simple Schema" layer of abstraction: they are included unconditionally.
+	 * Options for filtering out staged schemas from view schema are available in {@link extractPersistedSchema}.
 	 */
 	readonly definitions: ReadonlyMap<string, SimpleNodeSchema>;
 }