@fluidframework/tree 2.50.0 → 2.51.0-347100

package/src/shared-tree/schematizingTreeView.ts

@@ -16,10 +16,9 @@ import { anchorSlot, type SchemaPolicy } from "../core/index.js";
 import {
 	type NodeIdentifierManager,
 	defaultSchemaPolicy,
-	ContextSlot,
 	cursorForMapTreeNode,
-	type FullSchemaPolicy,
 	TreeStatus,
+	Context,
 } from "../feature-libraries/index.js";
 import {
 	type ImplicitFieldSchema,
@@ -53,6 +52,7 @@ import {
 	createUnknownOptionalFieldPolicy,
 	prepareForInsertionContextless,
 	type FieldSchema,
+	tryDisposeTreeNode,
 } from "../simple-tree/index.js";
 import {
 	type Breakable,
@@ -61,7 +61,6 @@ import {
 	type WithBreakable,
 } from "../util/index.js";
 
-import { CheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
 import { canInitialize, ensureSchema, initialize } from "./schematizeTree.js";
 import type { ITreeCheckout, TreeCheckout } from "./treeCheckout.js";
 
@@ -80,11 +79,11 @@ export class SchematizingSimpleTreeView<
 > implements TreeBranch, TreeViewAlpha<TRootSchema>, WithBreakable
 {
 	/**
-	 * The view is set to undefined when this object is disposed or the view schema does not support viewing the document's stored schema.
+	 * This is set to undefined when this object is disposed or the view schema does not support viewing the document's stored schema.
 	 *
 	 * The view schema may be incompatible with the stored schema. Use `compatibility` to check.
 	 */
-	private view: CheckoutFlexTreeView | undefined;
+	private flexTreeContext: Context | undefined;
 
 	/**
 	 * Undefined iff uninitialized or disposed.
@@ -97,6 +96,11 @@ export class SchematizingSimpleTreeView<
 
 	private readonly viewSchema: SchemaCompatibilityTester;
 
+	/**
+	 * Events to unregister upon flex-tree view disposal.
+	 */
+	private readonly flexTreeViewUnregisterCallbacks = new Set<() => void>();
+
 	/**
 	 * Events to unregister upon disposal.
 	 */
@@ -203,7 +207,7 @@ export class SchematizingSimpleTreeView<
 
 		if (!compatibility.canUpgrade) {
 			throw new UsageError(
-				"Existing stored schema can not be upgraded (see TreeView.compatibility.canUpgrade).",
+				"Existing stored schema cannot be upgraded (see TreeView.compatibility.canUpgrade).",
 			);
 		}
 
@@ -214,12 +218,12 @@ export class SchematizingSimpleTreeView<
 	}
 
 	/**
-	 * Gets the view. Throws when disposed.
+	 * Gets the flex-tree context. Throws when disposed or out of schema.
 	 */
-	public getView(): CheckoutFlexTreeView {
+	public getFlexTreeContext(): Context {
 		this.ensureUndisposed();
-		assert(this.view !== undefined, 0x8c0 /* unexpected getViewOrError */);
-		return this.view;
+		assert(this.flexTreeContext !== undefined, 0x8c0 /* unexpected getViewOrError */);
+		return this.flexTreeContext;
 	}
 
 	/**
@@ -301,82 +305,65 @@ export class SchematizingSimpleTreeView<
 	 * If implicit initialization (or some other edit) is desired, it should be done outside of this method.
 	 */
 	private update(): void {
-		this.disposeView();
+		this.disposeFlexView();
 
 		const compatibility = this.viewSchema.checkCompatibility(this.checkout.storedSchema);
 
-		let lastRoot =
-			this.compatibility.canView && this.view !== undefined ? this.root : undefined;
 		this.currentCompatibility = {
 			...compatibility,
 			canInitialize: canInitialize(this.checkout),
 		};
 
-		if (compatibility.canView) {
-			// Trigger "rootChanged" if the root changes in the future.
-			// Currently there is no good way to do this as FlexTreeField has no events for changes.
-			// this.view.flexTree.on(????)
-			// As a workaround for the above, trigger "rootChanged" in "afterBatch"
-			// which isn't the correct time since we normally do events during the batch when the forest is modified, but its better than nothing.
-			// TODO: provide a better event: this.view.flexTree.on(????)
-			const cleanupCheckOutEvents = this.checkout.events.on("afterBatch", () => {
-				// In the initialization flow, this event is raised before the correct compatibility w.r.t the new schema is calculated.
-				// Accessing `this.root` in that case can throw. It's OK to ignore this because:
-				// - 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;
-					this.events.emit("rootChanged");
-				}
-			});
-
-			const onViewDispose = (): void => {
-				cleanupCheckOutEvents();
-				this.view = undefined;
-				if (!this.disposed) {
-					this.update();
-				}
-			};
+		const anchors = this.checkout.forest.anchors;
+		const slots = anchors.slots;
 
-			const view = requireSchema(
+		if (compatibility.canView) {
+			this.flexTreeContext = new Context(
+				this.schemaPolicy,
 				this.checkout,
-				this.viewSchema,
-				onViewDispose,
 				this.nodeKeyManager,
-				this.schemaPolicy,
-			);
-			this.view = view;
-			assert(
-				!this.checkout.forest.anchors.slots.has(SimpleContextSlot),
-				0xa47 /* extra simple tree context */,
 			);
-			this.checkout.forest.anchors.slots.set(
+			assert(!slots.has(SimpleContextSlot), 0xa47 /* extra simple tree context */);
+			slots.set(
 				SimpleContextSlot,
 				new HydratedContext(
 					normalizeFieldSchema(this.rootFieldSchema).annotatedAllowedTypesNormalized,
-					view.context,
+					this.flexTreeContext,
 				),
 			);
 
-			const unregister = this.checkout.storedSchema.events.on("afterSchemaChange", () => {
-				unregister();
-				this.unregisterCallbacks.delete(unregister);
-				view[disposeSymbol]();
-			});
-			this.unregisterCallbacks.add(unregister);
-		} else {
-			this.view = undefined;
-			this.checkout.forest.anchors.slots.delete(SimpleContextSlot);
-
-			const unregister = this.checkout.storedSchema.events.on("afterSchemaChange", () => {
-				unregister();
-				this.unregisterCallbacks.delete(unregister);
-				this.update();
-			});
-			this.unregisterCallbacks.add(unregister);
+			// Trigger "rootChanged" events if the root changes in the future.
+			{
+				// Currently there is no good way to do this as FlexTreeField has no events for changes.
+				// this.root.on(????)
+				// As a workaround for the above, trigger "rootChanged" in "afterBatch".
+				// Ideally these events would be just events for changes within the root.
+				// 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.flexTreeViewUnregisterCallbacks.add(
+					this.checkout.events.on("afterBatch", () => {
+						// In the initialization flow, this event is raised before the correct compatibility w.r.t the new schema is calculated.
+						// Accessing `this.root` in that case can throw. It's OK to ignore this because:
+						// - 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;
+							this.events.emit("rootChanged");
+						}
+					}),
+				);
+			}
 		}
 
+		this.flexTreeViewUnregisterCallbacks.add(
+			// Will dispose the old view (if there is one) when its no longer valid, and create a new one if appropriate.
+			this.checkout.storedSchema.events.on("afterSchemaChange", () => this.update()),
+		);
+
 		if (!this.midUpgrade) {
 			this.events.emit("schemaChanged");
 			this.events.emit("rootChanged");
@@ -394,14 +381,20 @@ export class SchematizingSimpleTreeView<
 		this.events.emit("rootChanged");
 	}
 
-	private disposeView(): void {
-		if (this.view !== undefined) {
-			this.view[disposeSymbol]();
-			this.view = undefined;
-			this.checkout.forest.anchors.slots.delete(SimpleContextSlot);
-			this.unregisterCallbacks.forEach((unregister) => unregister());
+	private disposeFlexView(): void {
+		const anchors = this.checkout.forest.anchors;
+		if (this.flexTreeContext !== undefined) {
+			// Cleanup any TreeNodes cached in the AnchorSet when disposing the flex-tree which they wrap.
+			for (const anchorNode of anchors) {
+				tryDisposeTreeNode(anchorNode);
+			}
+
+			this.flexTreeContext[disposeSymbol]();
+			this.flexTreeContext = undefined;
 		}
-		this.checkout.forest.anchors.slots.delete(SimpleContextSlot);
+		this.flexTreeViewUnregisterCallbacks.forEach((unregister) => unregister());
+		this.flexTreeViewUnregisterCallbacks.clear();
+		anchors.slots.delete(SimpleContextSlot);
 	}
 
 	public get compatibility(): SchemaCompatibilityStatus {
@@ -413,7 +406,8 @@ export class SchematizingSimpleTreeView<
 
 	public dispose(): void {
 		this.disposed = true;
-		this.disposeView();
+		this.disposeFlexView();
+		this.unregisterCallbacks.forEach((unregister) => unregister());
 		this.checkout.forest.anchors.slots.delete(ViewSlot);
 		this.currentCompatibility = undefined;
 		this.onDispose?.();
@@ -430,8 +424,8 @@ export class SchematizingSimpleTreeView<
 				"Document is out of schema. Check TreeView.compatibility before accessing TreeView.root.",
 			);
 		}
-		const view = this.getView();
-		return tryGetTreeNodeForField(view.flexTree) as ReadableField<TRootSchema>;
+		const view = this.getFlexTreeContext();
+		return tryGetTreeNodeForField(view.root) as ReadableField<TRootSchema>;
 	}
 
 	public set root(newRoot: InsertableField<TRootSchema>) {
@@ -441,12 +435,8 @@ export class SchematizingSimpleTreeView<
 				"Document is out of schema. Check TreeView.compatibility before accessing TreeView.root.",
 			);
 		}
-		const view = this.getView();
-		setField(
-			view.context.root,
-			this.rootFieldSchema,
-			newRoot as InsertableContent | undefined,
-		);
+		const view = this.getFlexTreeContext();
+		setField(view.root, this.rootFieldSchema, newRoot as InsertableContent | undefined);
 	}
 
 	// #region Branching
@@ -478,31 +468,6 @@ export function getCheckout(context: TreeBranch): TreeCheckout {
 	throw new UsageError("Unsupported context implementation");
 }
 
-/**
- * Creates a view that self-disposes whenever the stored schema changes.
- * This may only be called when the schema is already known to be compatible (typically via ensureSchema).
- */
-export function requireSchema(
-	checkout: ITreeCheckout,
-	viewSchema: SchemaCompatibilityTester,
-	onDispose: () => void,
-	nodeKeyManager: NodeIdentifierManager,
-	schemaPolicy: FullSchemaPolicy,
-): CheckoutFlexTreeView {
-	const slots = checkout.forest.anchors.slots;
-	assert(!slots.has(ContextSlot), 0x8c2 /* Cannot create second view from checkout */);
-
-	{
-		const compatibility = viewSchema.checkCompatibility(checkout.storedSchema);
-		assert(compatibility.canView, 0x8c3 /* requireSchema invoked with incompatible schema */);
-	}
-
-	const view = new CheckoutFlexTreeView(checkout, schemaPolicy, nodeKeyManager, onDispose);
-	assert(slots.has(ContextSlot), 0x90d /* Context should be tracked in slot */);
-
-	return view;
-}
-
 /**
  * Adds constraints to a `checkout`'s pending transaction.
  *

package/src/shared-tree/sharedTreeChangeTypes.ts

@@ -16,7 +16,7 @@ export type SharedTreeInnerChange =
 export interface SharedTreeChange {
 	/**
 	 * The changes to apply.
-	 * @remarks while not expressable in TypeScript, these changes should never have two `ModularChangeset`s adjacent in the list.
+	 * @remarks while not expressible in TypeScript, these changes should never have two `ModularChangeset`s adjacent in the list.
 	 * This restriction exists because this change type should preserve the composition behavior of `ModularChangeFamily`, which
 	 * always composes runs of `ModularChangeset`s into a single `ModularChangeset`.
 	 */

package/src/shared-tree/tree.ts

@@ -4,6 +4,7 @@
  */
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 
 import {
 	type ImplicitFieldSchema,
@@ -16,12 +17,12 @@ import {
 	type TransactionConstraint,
 } from "../simple-tree/index.js";
 
-import { getCheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
 import {
 	addConstraintsToTransaction,
 	SchematizingSimpleTreeView,
 } from "./schematizingTreeView.js";
 import type { ITreeCheckout } from "./treeCheckout.js";
+import { Context } from "../feature-libraries/index.js";
 
 /**
  * Provides various functions for interacting with {@link TreeNode}s.
@@ -449,8 +450,8 @@ export function runTransaction<
 				"Transactions cannot be run on Unhydrated nodes. Transactions apply to a TreeView and Unhydrated nodes are not part of a TreeView.",
 			);
 		}
-		const treeView = getCheckoutFlexTreeView(context);
-		return runTransactionInCheckout(treeView.checkout, () => t(node), preconditions);
+		assert(context instanceof Context, "Expected context to be a Context instance.");
+		return runTransactionInCheckout(context.checkout, () => t(node), preconditions);
 	}
 }
 

package/src/shared-tree/treeAlpha.ts

@@ -191,6 +191,12 @@ export interface TreeIdentifierUtils {
  * Extensions to {@link (Tree:interface)} and {@link (TreeBeta:interface)} which are not yet stable.
  * @remarks
  * Use via the {@link (TreeAlpha:variable)} singleton.
+ * @privateRemarks
+ * TODO: AB#43548:
+ * How all the create and all the import and export APIs handle unknown optional fields needs to be figured out, tested and documented.
+ * This will need to be extended/generalized to cover other future schema evolution options as well once they exist.
+ * See also TreeBeta.clone with a similar issue.
+ *
  * @system @sealed @alpha
  */
 export interface TreeAlpha {
@@ -214,7 +220,7 @@ export interface TreeAlpha {
 	 * This function exists as a generalization that can be used in other cases as well,
 	 * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.
 	 * @privateRemarks
-	 * There should be a way to provide a source for defaulted identifiers, either via this API or some way to add them to its output later.
+	 * TODO: AB#43548: There should be a way to provide a source for defaulted identifiers, either via this API or some way to add them to its output later.
 	 */
 	create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(
 		schema: UnsafeUnknownSchema extends TSchema

package/src/shared-tree/treeCheckout.ts

@@ -46,8 +46,10 @@ import {
 import {
 	type FieldBatchCodec,
 	type TreeCompressionStrategy,
+	allowsRepoSuperset,
 	buildForest,
 	createNodeIdentifierManager,
+	defaultSchemaPolicy,
 	intoDelta,
 	jsonableTreeFromCursor,
 	makeFieldBatchCodec,
@@ -229,8 +231,13 @@ export interface ITreeCheckout extends AnchorLocator, ViewableTree, WithBreakabl
 	/**
 	 * Replaces all schema with the provided schema.
 	 * Can over-write preexisting schema, and removes unmentioned schema.
+	 *
+	 * @param newSchema - The new schema to replace the existing schema.
+	 * @param allowNonSupersetSchema - Whether to allow non-superset schemas.
+	 * Defaults to false.
+	 * If false, an assert will be thrown if the new schema does not permit all possible documents which were permitted under the old schema.
 	 */
-	updateSchema(newSchema: TreeStoredSchema): void;
+	updateSchema(newSchema: TreeStoredSchema, allowNonSupersetSchema?: true): void;
 
 	/**
 	 * Events about this view.
@@ -776,8 +783,14 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		}
 	}
 
-	public updateSchema(newSchema: TreeStoredSchema): void {
+	public updateSchema(newSchema: TreeStoredSchema, allowNonSupersetSchema?: true): void {
 		this.checkNotDisposed();
+		if (allowNonSupersetSchema !== true) {
+			assert(
+				allowsRepoSuperset(defaultSchemaPolicy, this.storedSchema.clone(), newSchema),
+				"New schema must allow all documents allowed by old schema",
+			);
+		}
 		this.editor.schema.setStoredSchema(this.storedSchema.clone(), newSchema);
 	}
 

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

@@ -6,9 +6,8 @@
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 
 import type { ITreeCursor } from "../../core/index.js";
-import type { TreeNodeSchema } from "../core/index.js";
+import type { TreeNodeSchema, TreeLeafValue, ImplicitAllowedTypes } from "../core/index.js";
 import { getUnhydratedContext } from "../createContext.js";
-import type { TreeLeafValue, ImplicitAllowedTypes } from "../schemaTypes.js";
 
 import {
 	customFromCursor,

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

@@ -15,13 +15,16 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import {
 	type FieldSchemaAlpha,
 	type ImplicitFieldSchema,
-	evaluateLazySchema,
 	FieldKind,
+	normalizeFieldSchema,
+} from "../fieldSchema.js";
+import {
+	NodeKind,
+	type TreeNodeSchema,
 	isAnnotatedAllowedType,
+	evaluateLazySchema,
 	markSchemaMostDerived,
-	normalizeFieldSchema,
-} from "../schemaTypes.js";
-import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+} from "../core/index.js";
 import { toStoredSchema } from "../toStoredSchema.js";
 import {
 	isArrayNodeSchema,

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

@@ -12,7 +12,7 @@ import {
 	type ITreeCursorSynchronous,
 	type SchemaAndPolicy,
 } from "../../core/index.js";
-import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../schemaTypes.js";
+import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../fieldSchema.js";
 import {
 	type Context,
 	getOrCreateNodeFromInnerNode,
@@ -37,6 +37,8 @@ import { unknownTypeError } from "./customTree.js";
  * @remarks
  * Does not support defaults.
  * Validates the field is in schema.
+ *
+ * TODO: AB#43548: How this handles unknown optional fields needs to be figured out, tested and documented.
  */
 export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 	schema: TSchema,

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

@@ -22,7 +22,7 @@ import {
 } from "../../core/index.js";
 import { FieldKinds, valueSchemaAllows } from "../../feature-libraries/index.js";
 import { cloneWithReplacements } from "../../util/index.js";
-import type { TreeNodeSchema } from "../core/index.js";
+import type { TreeNodeSchema, TreeLeafValue } from "../core/index.js";
 import {
 	booleanSchema,
 	handleSchema,
@@ -31,7 +31,6 @@ import {
 	stringSchema,
 } from "../leafNodeSchema.js";
 import { isArrayNodeSchema, isObjectNodeSchema } from "../node-kinds/index.js";
-import type { TreeLeafValue } from "../schemaTypes.js";
 
 /**
  * Options for how to interpret or encode a tree when schema information is available.

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

@@ -4,7 +4,7 @@
  */
 
 import type { JsonTreeSchema } from "./jsonSchema.js";
-import type { ImplicitAllowedTypes } from "../schemaTypes.js";
+import type { ImplicitAllowedTypes } from "../core/index.js";
 import { toJsonSchema } from "./simpleSchemaToJsonSchema.js";
 import type { TreeEncodingOptions } from "./customTree.js";
 import { TreeViewConfigurationAlpha } from "./configuration.js";

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { ImplicitFieldSchema } from "../schemaTypes.js";
+import type { ImplicitFieldSchema } from "../fieldSchema.js";
 import type { SimpleTreeSchema } from "../simpleSchema.js";
 
 import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";

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

@@ -5,7 +5,7 @@
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import type { TreeIndexKey } from "../../feature-libraries/index.js";
-import { FieldKind, type ImplicitFieldSchema } from "../schemaTypes.js";
+import { FieldKind, type ImplicitFieldSchema } from "../fieldSchema.js";
 import type { TreeNode } from "../core/index.js";
 import { ObjectNodeSchema } from "../node-kinds/index.js";
 import type { TreeView } from "./tree.js";

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

@@ -30,6 +30,8 @@ export {
 	type SchemaFactoryObjectOptions,
 	type SchemaStatics,
 	schemaStatics,
+	type NodeSchemaOptions,
+	type NodeSchemaOptionsAlpha,
 } from "./schemaFactory.js";
 export { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
 export type {

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

@@ -23,7 +23,7 @@ import {
 	fieldRealizer,
 	comparePosetElements,
 } from "../../feature-libraries/index.js";
-import type { FieldSchema } from "../schemaTypes.js";
+import type { FieldSchema } from "../fieldSchema.js";
 import { toStoredSchema } from "../toStoredSchema.js";
 
 import type { SchemaCompatibilityStatus } from "./tree.js";

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

@@ -4,11 +4,11 @@
  */
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { fail } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 
 import type { SchemaFactory, ScopedSchemaName } from "./schemaFactory.js";
-import type { NodeFromSchema } from "../schemaTypes.js";
 import type {
+	NodeFromSchema,
 	InternalTreeNode,
 	NodeKind,
 	TreeNode,
@@ -47,6 +47,12 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 		public get value(): TName {
 			return name;
 		}
+
+		public static override toString(): string {
+			return `SingletonSchema(${name})`;
+		}
+
+		public static [Symbol.toStringTag] = `SingletonSchema(${name})`;
 	}
 
 	type SingletonNodeType = TreeNode & { readonly value: TName };
@@ -71,10 +77,16 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 
 /**
  * Converts an enum into a collection of schema which can be used in a union.
+ *
+ * @typeParam TScope - The scope of the provided factory.
+ * There is a known issue where if a factory is provided that is typed as a {@link SchemaFactoryAlpha}, and its scope contains a "." character,
+ * the inferred type for the scope will end up as a union of the scope up to the first "." character and the scope as it should be.
+ * This can be mitigated by explicitly providing the TScope type parameter or by typing the provided factory as a {@link SchemaFactory} instead of a {@link SchemaFactoryAlpha}.
+ *
  * @remarks
  * The string value of the enum is used as the name of the schema: callers must ensure that it is stable and unique.
  * Numeric enums values have the value implicitly converted into a string.
- * Consider making a dedicated schema factory with a nested scope to avoid the enum members colliding with other schema.
+ * Consider making a dedicated schema factory with a nested scope (for example using {@link SchemaFactoryAlpha.scopedFactory}) to avoid the enum members colliding with other schema.
  * @example
  * ```typescript
  * const schemaFactory = new SchemaFactory("com.myApp");
@@ -105,7 +117,8 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * }
  * ```
  * @privateRemarks
- * Maybe provide `SchemaFactory.nested` to ease creating nested scopes?
+ * TODO: AB#43345: see TScope known issue above, and other references to this work item.
+ *
  * @see {@link enumFromStrings} for a similar function that works on arrays of strings instead of an enum.
  * @beta
  */
@@ -144,7 +157,7 @@ export function adaptEnum<
 			: never;
 	};
 	const out = factoryOut as typeof factoryOut & TOut & { readonly schema: SchemaArray };
-	for (const [key, value] of Object.entries(members)) {
+	for (const [key, value] of enumEntries(members)) {
 		const schema = singletonSchema(factory, value);
 		schemaArray.push(schema);
 		Object.defineProperty(out, key, {
@@ -165,6 +178,35 @@ export function adaptEnum<
 	return out;
 }
 
+/**
+ * Returns en "entries" (like Object.entries) for an enum object, omitting the
+ * {@link https://www.typescriptlang.org/docs/handbook/enums.html#reverse-mappings|reverse mappings}
+ */
+export function enumEntries(
+	enumObject: Record<string, string | number>,
+): [string, string | number][] {
+	// Skip reverse mapping for numeric entries.
+	// For numeric entries, TypeScript defines an additional property keyed with the number implicitly converted to a string.
+	// Note TypeScript can overwrite its own enum entries in some edge cases (see https://github.com/microsoft/TypeScript/issues/48956), so it's not possible to handle all cases correctly.
+	return Object.entries(enumObject).filter(([key, value]) => {
+		// All reverse mapping must also have a inverse mapping (the regular forward mapping) to a number:
+		const inverse = enumObject[value];
+		if (typeof inverse !== "number") {
+			// Known not to be a reverse mapping, so keep it.
+			return true;
+		}
+		// At this point, it is expected that all remaining cases are reverse mappings,
+		// but do some asserts to ensure that the above logic is sufficient.
+		assert(typeof value === "string", "expected reverse mapping and thus a string value");
+		assert(
+			Number.parseFloat(key).toString() === key,
+			"expected reverse mapping and thus a key that is a normalized number",
+		);
+		// Discard the reverse mapping.
+		return false;
+	});
+}
+
 /**
  * Converts an array of distinct strings into a collection of schema which can be used like an enum style union.
  * @remarks