@fluidframework/tree 2.72.0 → 2.74.0-365691

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

@@ -4,18 +4,15 @@
  */
 
 import { brand } from "../../util/index.js";
-import {
-	normalizeAndEvaluateAnnotatedAllowedTypes,
-	type AnnotatedAllowedType,
-	type ImplicitAllowedTypes,
-	type SchemaUpgrade,
-} from "./allowedTypes.js";
+import type { SchemaUpgrade } from "./allowedTypes.js";
 import type { TreeNodeSchemaIdentifier, TreeTypeSet } from "../../core/index.js";
+import type { SimpleAllowedTypeAttributes, SimpleAllowedTypes } from "../simpleSchema.js";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 /**
  * Options for generating a {@link TreeStoredSchema} from view schema.
  */
-export interface StoredSchemaGenerationOptions {
+export interface StoredFromViewSchemaGenerationOptions {
 	/**
 	 * Determines whether to include staged schema in the resulting stored schema.
 	 * @remarks
@@ -24,6 +21,16 @@ export interface StoredSchemaGenerationOptions {
 	includeStaged(upgrade: SchemaUpgrade): boolean;
 }
 
+/**
+ * Marker type indicating that the input schema is already a stored schema.
+ */
+export const ExpectStored = Symbol("ExpectStored");
+export type ExpectStored = typeof ExpectStored;
+
+export type StoredSchemaGenerationOptions =
+	| StoredFromViewSchemaGenerationOptions
+	| ExpectStored;
+
 /**
  * Filters an allowed type based on the provided options.
  * @param allowedType - The allowed type to filter.
@@ -31,30 +38,47 @@ export interface StoredSchemaGenerationOptions {
  * @returns Whether the allowed type passes the filter.
  */
 export function allowedTypeFilter(
-	allowedType: AnnotatedAllowedType,
+	data: SimpleAllowedTypeAttributes,
 	options: StoredSchemaGenerationOptions,
 ): boolean {
+	if (options === ExpectStored) {
+		if (data.isStaged !== undefined) {
+			throw new UsageError(
+				"Failed to covert view schema to stored schema. The simple schema provided was indicated to be a stored schema by the use of `ExpectStored`, but view schema specific content was encountered which requires a `StoredFromViewSchemaGenerationOptions` to process.",
+			);
+		}
+		return true;
+	}
+
+	if (data.isStaged === undefined) {
+		throw new UsageError(
+			"Failed to covert view schema to stored schema. The simple schema provided as the view schema was actually a stored schema. If this was intended, use `ExpectStored` for the `StoredSchemaGenerationOptions` to indicate the input is already a stored schema and only a format conversion is required.",
+		);
+	}
+
 	// If the allowed type is staged, only include it if the options allow it.
-	if (allowedType.metadata.stagedSchemaUpgrade !== undefined) {
-		return options.includeStaged(allowedType.metadata.stagedSchemaUpgrade);
+	if (data.isStaged === false) {
+		return true;
 	}
-	return true;
+
+	return options.includeStaged(data.isStaged);
 }
 
 /**
- * Converts an ImplicitAllowedTypes to a stored schema.
+ * Converts a {@link SimpleAllowedTypes} to a stored schema.
  * @param schema - The schema to convert.
  * @param options - The options to use for filtering.
  * @returns The converted stored schema.
  */
 export function convertAllowedTypes(
-	schema: ImplicitAllowedTypes,
+	schema: SimpleAllowedTypes,
 	options: StoredSchemaGenerationOptions,
 ): TreeTypeSet {
-	const filtered: TreeNodeSchemaIdentifier[] = normalizeAndEvaluateAnnotatedAllowedTypes(
-		schema,
-	)
-		.types.filter((allowedType) => allowedTypeFilter(allowedType, options))
-		.map((a) => brand(a.type.identifier));
+	const filtered: TreeNodeSchemaIdentifier[] = [];
+	for (const [type, data] of schema) {
+		if (allowedTypeFilter(data, options)) {
+			filtered.push(brand<TreeNodeSchemaIdentifier>(type));
+		}
+	}
 	return new Set(filtered);
 }

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

@@ -294,6 +294,7 @@ export class TreeNodeKernel {
 	}
 }
 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 const kernelEvents = ["childrenChangedAfterBatch", "subtreeChangedAfterBatch"] as const;
 
 type KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;

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

@@ -12,10 +12,9 @@ import type { InternalTreeNode, Unhydrated } from "./types.js";
 import type { UnionToIntersection } from "../../util/index.js";
 import type { AllowedTypesFullEvaluated, AllowedTypesFull } from "./allowedTypes.js";
 import type { Context } from "./context.js";
-import type { FieldKey, NodeData, TreeNodeStoredSchema } from "../../core/index.js";
+import type { FieldKey, NodeData } from "../../core/index.js";
 import type { UnhydratedFlexTreeField } from "./unhydratedFlexTree.js";
 import type { FactoryContent } from "../unhydratedFlexTreeFromInsertable.js";
-import type { StoredSchemaGenerationOptions } from "./toStored.js";
 
 /**
  * Schema for a {@link TreeNode} or {@link TreeLeafValue}.
@@ -389,11 +388,6 @@ export interface TreeNodeSchemaPrivateData {
 	 * Idempotent initialization function that pre-caches data and can dereference lazy schema references.
 	 */
 	idempotentInitialize(): TreeNodeSchemaInitializedData;
-
-	/**
-	 * Converts a the schema into a {@link TreeNodeStoredSchema}.
-	 */
-	toStored(options: StoredSchemaGenerationOptions): TreeNodeStoredSchema;
 }
 
 /**

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

@@ -260,7 +260,6 @@ export function isClassBasedSchema(
 export function createTreeNodeSchemaPrivateData(
 	schema: TreeNodeSchemaCore<string, NodeKind, boolean>,
 	childAllowedTypes: readonly AllowedTypesFull[],
-	toStored: TreeNodeSchemaPrivateData["toStored"],
 ): TreeNodeSchemaPrivateData {
 	const schemaValid = schemaAsTreeNodeValid(schema);
 	// Since this closes over the schema, ensure this schema is marked as most derived
@@ -270,7 +269,6 @@ export function createTreeNodeSchemaPrivateData(
 	return {
 		idempotentInitialize: () => schemaValid.oneTimeInitialize().oneTimeInitialized,
 		childAllowedTypes,
-		toStored,
 	};
 }
 

package/src/simple-tree/fieldSchema.ts

@@ -29,7 +29,7 @@ import type {
 	InsertableTreeNodeFromImplicitAllowedTypes,
 	AllowedTypesFull,
 } from "./core/index.js";
-import { normalizeAllowedTypes } from "./core/index.js";
+import { AnnotatedAllowedTypesInternal, normalizeAllowedTypes } from "./core/index.js";
 
 import type { SimpleAllowedTypeAttributes, SimpleFieldSchema } from "./simpleSchema.js";
 import type { UnsafeUnknownSchema } from "./unsafeUnknownSchema.js";
@@ -413,16 +413,7 @@ export class FieldSchemaAlpha<
 	}
 
 	public get simpleAllowedTypes(): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
-		const types = this.allowedTypesFull.evaluate().types;
-		const info = new Map<string, SimpleAllowedTypeAttributes>();
-
-		for (const type of types) {
-			info.set(type.type.identifier, {
-				isStaged: type.metadata.stagedSchemaUpgrade !== undefined,
-			});
-		}
-
-		return info;
+		return AnnotatedAllowedTypesInternal.evaluateSimpleAllowedTypes(this.allowedTypesFull);
 	}
 
 	protected constructor(

package/src/simple-tree/index.ts

@@ -44,7 +44,7 @@ export {
 	type UnannotateAllowedTypesList,
 	type AllowedTypeMetadata,
 	type AnnotatedAllowedTypes,
-	type SchemaUpgrade,
+	SchemaUpgrade,
 	type LazyItem,
 	type FlexList,
 	type FlexListToUnion,
@@ -59,6 +59,8 @@ export {
 	type AllowedTypesFullFromMixed,
 	AnnotatedAllowedTypesInternal,
 	type NumberKeys,
+	ExpectStored,
+	createSchemaUpgrade,
 } from "./core/index.js";
 export { walkFieldSchema } from "./walkFieldSchema.js";
 export type { UnsafeUnknownSchema, Insertable } from "./unsafeUnknownSchema.js";
@@ -184,7 +186,7 @@ export {
 	KeyEncodingOptions,
 	type TreeParsingOptions,
 	incrementalSummaryHint,
-	getShouldIncrementallySummarizeAllowedTypes,
+	incrementalEncodingPolicyForAllowedTypes,
 	type SchemaFactory_base,
 } from "./api/index.js";
 export type {
@@ -283,4 +285,7 @@ export type { LeafSchema } from "./leafNodeSchema.js";
 export {
 	encodeSimpleSchema,
 	decodeSimpleSchema,
+	exportCompatibilitySchemaSnapshot,
+	importCompatibilitySchemaSnapshot,
+	checkCompatibility,
 } from "./api/index.js";

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

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

@@ -45,7 +45,6 @@ import {
 	createTreeNodeSchemaPrivateData,
 	type FlexContent,
 	type TreeNodeSchemaPrivateData,
-	convertAllowedTypes,
 	withBufferedTreeEvents,
 	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
@@ -66,9 +65,13 @@ import type {
 	ArrayNodePojoEmulationSchema,
 	ArrayNodeSchema,
 } from "./arrayNodeTypes.js";
-import { brand, type JsonCompatibleReadOnlyObject } from "../../../util/index.js";
+import {
+	brand,
+	validateIndex,
+	validateIndexRange,
+	type JsonCompatibleReadOnlyObject,
+} from "../../../util/index.js";
 import { nullSchema } from "../../leafNodeSchema.js";
-import { arrayNodeStoredSchema } from "../../toStoredSchema.js";
 import type { SimpleAllowedTypeAttributes } from "../../simpleSchema.js";
 
 /**
@@ -575,6 +578,7 @@ const TreeNodeWithArrayFeatures = (() => {
  */
 /* eslint-disable @typescript-eslint/explicit-member-accessibility, @typescript-eslint/no-explicit-any */
 // prettier-ignore
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 declare abstract class NodeWithArrayFeatures<Input, T>
 	extends TreeNodeValid<Input>
 	implements Pick<readonly T[], (typeof arrayPrototypeKeys)[number]>
@@ -951,7 +955,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	}
 	public insertAt(index: number, ...value: Insertable<T>): void {
 		const field = getSequenceField(this);
-		validateIndex(index, field, "insertAt", true);
+		validateIndex(index, field, "TreeArrayNode.insertAt", true);
 		const content = this.#mapTreesFromFieldData(value);
 		field.editor.insert(index, content);
 	}
@@ -963,32 +967,30 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	}
 	public removeAt(index: number): void {
 		const field = getSequenceField(this);
-		validateIndex(index, field, "removeAt");
+		validateIndex(index, field, "TreeArrayNode.removeAt");
 		field.editor.remove(index, 1);
 	}
 	public removeRange(start?: number, end?: number): void {
 		const field = getSequenceField(this);
 		const { length } = field;
 		const removeStart = start ?? 0;
+		validateIndex(removeStart, field, "TreeArrayNode.removeRange", true);
+
 		const removeEnd = Math.min(length, end ?? length);
-		validatePositiveIndex(removeStart);
-		validatePositiveIndex(removeEnd);
-		if (removeEnd < removeStart) {
-			// This catches both the case where start is > array.length and when start is > end.
-			throw new UsageError('Too large of "start" value passed to TreeArrayNode.removeRange.');
-		}
+		validateIndexRange(removeStart, removeEnd, field, "TreeArrayNode.removeRange");
+
 		field.editor.remove(removeStart, removeEnd - removeStart);
 	}
 	public moveToStart(sourceIndex: number, source?: ReadonlyArrayNode): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);
-		validateIndex(sourceIndex, sourceField, "moveToStart");
+		validateIndex(sourceIndex, sourceField, "TreeArrayNode.moveToStart");
 		this.moveRangeToIndex(0, sourceIndex, sourceIndex + 1, source);
 	}
 	public moveToEnd(sourceIndex: number, source?: ReadonlyArrayNode): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);
-		validateIndex(sourceIndex, sourceField, "moveToEnd");
+		validateIndex(sourceIndex, sourceField, "TreeArrayNode.moveToEnd");
 		this.moveRangeToIndex(this.length, sourceIndex, sourceIndex + 1, source);
 	}
 	public moveToIndex(
@@ -999,8 +1001,8 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);
 		const destinationField = getSequenceField(this);
-		validateIndex(destinationGap, destinationField, "moveToIndex", true);
-		validateIndex(sourceIndex, sourceField, "moveToIndex");
+		validateIndex(destinationGap, destinationField, "TreeArrayNode.moveToIndex", true);
+		validateIndex(sourceIndex, sourceField, "TreeArrayNode.moveToIndex");
 		this.moveRangeToIndex(destinationGap, sourceIndex, sourceIndex + 1, source);
 	}
 	public moveRangeToStart(
@@ -1012,7 +1014,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			sourceStart,
 			sourceEnd,
 			source ?? getSequenceField(this),
-			"moveRangeToStart",
+			"TreeArrayNode.moveRangeToStart",
 		);
 		this.moveRangeToIndex(0, sourceStart, sourceEnd, source);
 	}
@@ -1025,7 +1027,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			sourceStart,
 			sourceEnd,
 			source ?? getSequenceField(this),
-			"moveRangeToEnd",
+			"TreeArrayNode.moveRangeToEnd",
 		);
 		this.moveRangeToIndex(this.length, sourceStart, sourceEnd, source);
 	}
@@ -1044,8 +1046,13 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		).getFieldSchema(EmptyKey).types;
 		const sourceField = source !== undefined ? getSequenceField(source) : destinationField;
 
-		validateIndex(destinationGap, destinationField, "moveRangeToIndex", true);
-		validateIndexRange(sourceStart, sourceEnd, source ?? destinationField, "moveRangeToIndex");
+		validateIndex(destinationGap, destinationField, "TreeArrayNode.moveRangeToIndex", true);
+		validateIndexRange(
+			sourceStart,
+			sourceEnd,
+			source ?? destinationField,
+			"TreeArrayNode.moveRangeToIndex",
+		);
 
 		// TODO: determine support for move across different sequence types
 		if (sourceField !== destinationField) {
@@ -1282,12 +1289,7 @@ export function arraySchema<
 		}
 
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
-			return (privateData ??= createTreeNodeSchemaPrivateData(
-				this,
-				[normalizedTypes],
-				(storedOptions) =>
-					arrayNodeStoredSchema(convertAllowedTypes(info, storedOptions), persistedMetadata),
-			));
+			return (privateData ??= createTreeNodeSchemaPrivateData(this, [normalizedTypes]));
 		}
 	}
 
@@ -1295,56 +1297,6 @@ export function arraySchema<
 	return output;
 }
 
-function validateSafeInteger(index: number): void {
-	if (!Number.isSafeInteger(index)) {
-		throw new UsageError(`Expected a safe integer, got ${index}.`);
-	}
-}
-
-function validatePositiveIndex(index: number): void {
-	validateSafeInteger(index);
-	if (index < 0) {
-		throw new UsageError(`Expected non-negative index, got ${index}.`);
-	}
-}
-
-function validateIndex(
-	index: number,
-	array: { readonly length: number },
-	methodName: string,
-	allowOnePastEnd: boolean = false,
-): void {
-	validatePositiveIndex(index);
-	if (allowOnePastEnd) {
-		if (index > array.length) {
-			throw new UsageError(
-				`Index value passed to TreeArrayNode.${methodName} is out of bounds.`,
-			);
-		}
-	} else {
-		if (index >= array.length) {
-			throw new UsageError(
-				`Index value passed to TreeArrayNode.${methodName} is out of bounds.`,
-			);
-		}
-	}
-}
-
-function validateIndexRange(
-	startIndex: number,
-	endIndex: number,
-	array: { readonly length: number },
-	methodName: string,
-): void {
-	validateIndex(startIndex, array, methodName, true);
-	validateIndex(endIndex, array, methodName, true);
-	if (startIndex > endIndex || array.length < endIndex) {
-		throw new UsageError(
-			`Index value passed to TreeArrayNode.${methodName} is out of bounds.`,
-		);
-	}
-}
-
 /**
  * Transforms data for a child of an array.
  * @param child - The tree data to be transformed.
@@ -1375,6 +1327,7 @@ function arrayChildToFlexTree(
  */
 function arrayToFlexContent(data: FactoryContent, schema: ArrayNodeSchema): FlexContent {
 	if (!(typeof data === "object" && data !== null && Symbol.iterator in data)) {
+		// eslint-disable-next-line @typescript-eslint/no-base-to-string
 		throw new UsageError(`Input data is incompatible with Array schema: ${data}`);
 	}
 

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

@@ -7,7 +7,6 @@ import { assert, Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
-	FieldKinds,
 	isTreeValue,
 	type FlexibleNodeContent,
 	type FlexTreeNode,
@@ -42,7 +41,6 @@ import {
 	createTreeNodeSchemaPrivateData,
 	type FlexContent,
 	type TreeNodeSchemaPrivateData,
-	convertAllowedTypes,
 	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
 import {
@@ -343,19 +341,7 @@ export function mapSchema<
 		}
 
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
-			return (privateData ??= createTreeNodeSchemaPrivateData(
-				this,
-				[normalizedTypes],
-				(storedOptions) =>
-					new MapNodeStoredSchema(
-						{
-							kind: FieldKinds.optional.identifier,
-							types: convertAllowedTypes(info, storedOptions),
-							persistedMetadata,
-						},
-						persistedMetadata,
-					),
-			));
+			return (privateData ??= createTreeNodeSchemaPrivateData(this, [normalizedTypes]));
 		}
 	}
 	const schemaErased: MapNodeCustomizableSchema<

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

@@ -86,7 +86,7 @@ import {
 	type FactoryContentObject,
 	type InsertableContent,
 } from "../../unhydratedFlexTreeFromInsertable.js";
-import { convertField, convertFieldKind } from "../../toStoredSchema.js";
+import { convertFieldKind } from "../../toStoredSchema.js";
 import type { ObjectSchemaOptionsAlpha } from "../../api/index.js";
 
 /**
@@ -99,7 +99,7 @@ import type { ObjectSchemaOptionsAlpha } from "../../api/index.js";
  */
 export type ObjectFromSchemaRecord<T extends RestrictiveStringRecord<ImplicitFieldSchema>> =
 	RestrictiveStringRecord<ImplicitFieldSchema> extends T
-		? // eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/ban-types
+		? // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 			{}
 		: {
 				-readonly [Property in keyof T]: Property extends string
@@ -585,20 +585,6 @@ export function objectSchema<
 			return (privateData ??= createTreeNodeSchemaPrivateData(
 				this,
 				Array.from(CustomObjectNode.fields.values(), (schema) => schema.allowedTypesFull),
-				(storedOptions) => {
-					const fields: Map<FieldKey, TreeFieldStoredSchema> = new Map();
-					for (const fieldSchema of flexKeyMap.values()) {
-						assert(
-							fieldSchema.schema instanceof FieldSchemaAlpha,
-							0xc19 /* Expected FieldSchemaAlpha */,
-						);
-						fields.set(
-							brand(fieldSchema.storedKey),
-							convertField(fieldSchema.schema, storedOptions),
-						);
-					}
-					return new ObjectNodeStoredSchema(fields, nodeOptions.persistedMetadata);
-				},
 			));
 		}
 	}
@@ -650,9 +636,8 @@ function assertUniqueKeys<
 }
 
 /**
- * {@link TreeNodeSchemaInitializedData.toFlexContent} for Map nodes.
+ * {@link TreeNodeSchemaInitializedData.toFlexContent} for object nodes.
  *
- * Transforms data under an Object schema.
  * @param data - The tree data to be transformed. Must be a Record-like object.
  * @param schema - The schema to comply with.
  */
@@ -666,6 +651,7 @@ function objectToFlexContent(
 		Symbol.iterator in data ||
 		isFluidHandle(data)
 	) {
+		// eslint-disable-next-line @typescript-eslint/no-base-to-string
 		throw new UsageError(`Input data is incompatible with Object schema: ${data}`);
 	}
 

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

@@ -31,7 +31,6 @@ import {
 	type FlexContent,
 	CompatibilityLevel,
 	type TreeNodeSchemaPrivateData,
-	convertAllowedTypes,
 	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
 import { getTreeNodeSchemaInitializedData } from "../../createContext.js";
@@ -50,7 +49,6 @@ import type {
 	TreeRecordNode,
 } from "./recordNodeTypes.js";
 import {
-	FieldKinds,
 	isTreeValue,
 	type FlexTreeNode,
 	type FlexTreeOptionalField,
@@ -388,19 +386,7 @@ export function recordSchema<
 		}
 
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
-			return (privateData ??= createTreeNodeSchemaPrivateData(
-				this,
-				[normalizedTypes],
-				(storedOptions) =>
-					new MapNodeStoredSchema(
-						{
-							kind: FieldKinds.optional.identifier,
-							types: convertAllowedTypes(info, storedOptions),
-							persistedMetadata,
-						},
-						persistedMetadata,
-					),
-			));
+			return (privateData ??= createTreeNodeSchemaPrivateData(this, [normalizedTypes]));
 		}
 	}
 

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, SimpleNodeSchemaBase } from "./core/index.js";
+import type { NodeKind, SchemaUpgrade, SimpleNodeSchemaBase } from "./core/index.js";
 import type { FieldKind, FieldSchemaMetadata } from "./fieldSchema.js";
 
 /*
@@ -39,6 +39,15 @@ export interface SimpleNodeSchemaBaseAlpha<
 	readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined;
 }
 
+/**
+ * {@link AllowedTypes} for a location in the tree, expressed for use in the Simple Schema layer of abstraction.
+ *
+ * @remarks
+ * Refers to the types by identifier.
+ * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
+ */
+export type SimpleAllowedTypes = ReadonlyMap<string, SimpleAllowedTypeAttributes>;
+
 /**
  * A {@link SimpleNodeSchema} for an object node.
  *
@@ -179,13 +188,17 @@ export type SimpleNodeSchema =
  */
 export interface SimpleAllowedTypeAttributes {
 	/**
-	 * True if this schema is included as a {@link SchemaStaticsBeta.staged | staged} schema upgrade,
+	 * {@link SchemaUpgrade} if this schema is included as a {@link SchemaStaticsBeta.staged | staged} schema upgrade,
 	 * allowing the view schema be compatible with stored schema with (post upgrade) or without it (pre-upgrade).
 	 * New documents and schema upgrades will omit any staged schema.
 	 *
 	 * Undefined if derived from a stored schema.
+	 *
+	 * @privateRemarks
+	 * The false and undefined cases here are a bit odd.
+	 * This API should be reevaluated before stabilizing.
 	 */
-	readonly isStaged: boolean | undefined;
+	readonly isStaged: false | SchemaUpgrade | undefined;
 }
 
 /**