@fluidframework/tree 2.1.0-276985 → 2.1.0

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

@@ -137,6 +137,13 @@ export interface SharedTreeBranchEvents<TEditor extends ChangeFamilyEditor, TCha
 	 */
 	transactionAborted(isOuterTransaction: boolean): void;
 
+	/**
+	 * Fired after the current transaction is completely rolled back.
+	 * @param isOuterTransaction - true iff the transaction being aborted is the outermost transaction
+	 * as opposed to a nested transaction.
+	 */
+	transactionRolledBack(isOuterTransaction: boolean): void;
+
 	/**
 	 * Fired after the current transaction is committed.
 	 * @param isOuterTransaction - true iff the transaction being committed is the outermost transaction
@@ -244,6 +251,7 @@ export class SharedTreeBranch<
 	): [change: TChange, newCommit: GraphCommit<TChange>] {
 		this.assertNotDisposed();
 
+		// TODO: This should not be necessary when receiving changes from other clients.
 		const changeWithRevision = this.changeFamily.rebaser.changeRevision(change, revision);
 
 		const newHead = mintCommit(this.head, {
@@ -360,6 +368,7 @@ export class SharedTreeBranch<
 
 		this.emit("transactionAborted", this.transactions.size === 0);
 		if (commits.length === 0) {
+			this.emit("transactionRolledBack", this.transactions.size === 0);
 			return [undefined, []];
 		}
 
@@ -386,6 +395,7 @@ export class SharedTreeBranch<
 		this.emit("beforeChange", changeEvent);
 		this.head = startCommit;
 		this.emit("afterChange", changeEvent);
+		this.emit("transactionRolledBack", this.transactions.size === 0);
 		return [change, commits];
 	}
 

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

@@ -34,7 +34,14 @@ import {
 	type SchemaPolicy,
 	type TreeStoredSchemaRepository,
 } from "../core/index.js";
-import { type JsonCompatibleReadOnly, brand } from "../util/index.js";
+import {
+	type JsonCompatibleReadOnly,
+	brand,
+	Breakable,
+	type WithBreakable,
+	throwIfBroken,
+	breakingClass,
+} from "../util/index.js";
 
 import { type SharedTreeBranch, getChangeReplaceType } from "./branch.js";
 import { EditManager, minimumPossibleSequenceNumber } from "./editManager.js";
@@ -62,12 +69,15 @@ export interface ClonableSchemaAndPolicy extends SchemaAndPolicy {
 }
 
 /**
- * Generic shared tree, which needs to be configured with indexes, field kinds and a history policy to be used.
- *
- * TODO: actually implement
- * TODO: is history policy a detail of what indexes are used, or is there something else to it?
+ * Generic shared tree, which needs to be configured with indexes, field kinds and other configuration.
  */
-export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange> extends SharedObject {
+@breakingClass
+export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
+	extends SharedObject
+	implements WithBreakable
+{
+	public readonly breaker: Breakable = new Breakable("Shared Tree");
+
 	private readonly editManager: EditManager<TEditor, TChange, ChangeFamily<TEditor, TChange>>;
 	private readonly summarizables: readonly Summarizable[];
 	/**
@@ -85,6 +95,13 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange> extends
 		return this.getLocalBranch().editor;
 	}
 
+	/**
+	 * Gets the revision at the head of the trunk.
+	 */
+	protected get trunkHeadRevision(): RevisionTag {
+		return this.editManager.getTrunkHead().revision;
+	}
+
 	/**
 	 * Used to encode/decode messages sent to/received from the Fluid runtime.
 	 *
@@ -262,6 +279,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange> extends
 
 	// TODO: SharedObject's merging of the two summary methods into summarizeCore is not what we want here:
 	// We might want to not subclass it, or override/reimplement most of its functionality.
+	@throwIfBroken
 	protected summarizeCore(
 		serializer: IFluidSerializer,
 		telemetryContext?: ITelemetryContext,
@@ -304,6 +322,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange> extends
 	 * @returns the submitted commit. This is undefined if the underlying `SharedObject` is not attached,
 	 * and may differ from `commit` due to enrichments like detached tree refreshers.
 	 */
+
 	private submitCommit(
 		commit: GraphCommit<TChange>,
 		schemaAndPolicy: ClonableSchemaAndPolicy,

package/src/simple-tree/arrayNode.ts

@@ -19,6 +19,7 @@ import {
 	getOrCreateMapTreeNode,
 	getSchemaAndPolicy,
 	isMapTreeNode,
+	isFlexTreeNode,
 } from "../feature-libraries/index.js";
 import {
 	type InsertableContent,
@@ -26,7 +27,7 @@ import {
 	markContentType,
 	prepareContentForHydration,
 } from "./proxies.js";
-import { getFlexNode } from "./proxyBinding.js";
+import { getFlexNode, getKernel } from "./proxyBinding.js";
 import {
 	NodeKind,
 	type ImplicitAllowedTypes,
@@ -39,7 +40,12 @@ import {
 	normalizeFieldSchema,
 } from "./schemaTypes.js";
 import { mapTreeFromNodeData } from "./toMapTree.js";
-import { type TreeNode, TreeNodeValid } from "./types.js";
+import {
+	type TreeNode,
+	TreeNodeValid,
+	type InternalTreeNode,
+	type MostDerivedData,
+} from "./types.js";
 import { fail } from "../util/index.js";
 import { getFlexSchema } from "./toFlexSchema.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
@@ -215,6 +221,11 @@ export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom>
 		sourceEnd: number,
 		source: TMoveFrom,
 	): void;
+
+	/**
+	 * Returns a custom IterableIterator which throws usage errors if concurrent editing and iteration occurs.
+	 */
+	values(): IterableIterator<T>;
 }
 
 /**
@@ -315,7 +326,6 @@ const arrayPrototypeKeys = [
 	"some",
 	"toLocaleString",
 	"toString",
-	"values",
 
 	// "copyWithin",
 	// "fill",
@@ -489,7 +499,6 @@ declare abstract class NodeWithArrayFeatures<Input, T>
 	): boolean;
 	toLocaleString(): string;
 	toString(): string;
-	values(): IterableIterator<T>;
 }
 /* eslint-enable @typescript-eslint/explicit-member-accessibility, @typescript-eslint/no-explicit-any */
 
@@ -554,16 +563,8 @@ function createArrayNodeProxy(
 				return Reflect.get(dispatchTarget, key, receiver) as unknown;
 			}
 
-			const value = field.boxedAt(maybeIndex);
-
-			if (value === undefined) {
-				return undefined;
-			}
-
-			// TODO: Ideally, we would return leaves without first boxing them.  However, this is not
-			//       as simple as calling '.content' since this skips the node and returns the FieldNode's
-			//       inner field.
-			return getOrCreateNodeProxy(value);
+			const maybeContent = field.at(maybeIndex);
+			return isFlexTreeNode(maybeContent) ? getOrCreateNodeProxy(maybeContent) : maybeContent;
 		},
 		set: (target, key, newValue, receiver) => {
 			if (key === "length") {
@@ -590,7 +591,7 @@ function createArrayNodeProxy(
 					"Cannot set indexed properties on array nodes. Use array node mutation APIs to alter the array.",
 				);
 			}
-			return allowAdditionalProperties ? Reflect.set(target, key, newValue) : false;
+			return allowAdditionalProperties ? Reflect.set(target, key, newValue, receiver) : false;
 		},
 		has: (target, key) => {
 			const field = getSequenceField(proxy);
@@ -672,6 +673,21 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 
 	protected abstract get simpleSchema(): T;
 
+	/**
+	 * Generation number which is incremented any time we have an edit on the node.
+	 * Used during iteration to make sure there has been no edits that were concurrently made.
+	 */
+	#generationNumber: number = 0;
+
+	public constructor(
+		input: Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>> | InternalTreeNode,
+	) {
+		super(input);
+		getKernel(this).on("nodeChanged", () => {
+			this.#generationNumber += 1;
+		});
+	}
+
 	#cursorFromFieldData(value: Insertable<T>): ITreeCursorSynchronous {
 		if (isMapTreeNode(getFlexNode(this))) {
 			throw new UsageError(`An array cannot be mutated before being inserted into the tree`);
@@ -827,13 +843,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		const destinationField = getSequenceField(this);
 		validateIndex(destinationIndex, destinationField, "moveRangeToIndex", true);
 		validateIndexRange(sourceStart, sourceEnd, source ?? destinationField, "moveRangeToIndex");
-		const sourceField =
-			source !== undefined
-				? destinationField.isSameAs(getSequenceField(source))
-					? destinationField
-					: getSequenceField(source)
-				: destinationField;
-
+		const sourceField = source !== undefined ? getSequenceField(source) : destinationField;
 		// TODO: determine support for move across different sequence types
 		if (destinationField.schema.types !== undefined && sourceField !== destinationField) {
 			for (let i = sourceStart; i < sourceEnd; i++) {
@@ -855,6 +865,23 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			destinationIndex,
 		);
 	}
+
+	public values(): IterableIterator<TreeNodeFromImplicitAllowedTypes<T>> {
+		return this.generateValues(this.#generationNumber);
+	}
+	private *generateValues(
+		initialLastUpdatedStamp: number,
+	): Generator<TreeNodeFromImplicitAllowedTypes<T>> {
+		if (initialLastUpdatedStamp !== this.#generationNumber) {
+			throw new UsageError(`Concurrent editing and iteration is not allowed.`);
+		}
+		for (let i = 0; i < this.length; i++) {
+			yield this.at(i) ?? fail("Index is out of bounds");
+			if (initialLastUpdatedStamp !== this.#generationNumber) {
+				throw new UsageError(`Concurrent editing and iteration is not allowed.`);
+			}
+		}
+	}
 }
 
 /**
@@ -921,7 +948,7 @@ export function arraySchema<
 			);
 		}
 
-		protected static override constructorCached: typeof TreeNodeValid | undefined = undefined;
+		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup<T2>(this: typeof TreeNodeValid<T2>): void {
 			flexSchema = getFlexSchema(this as unknown as TreeNodeSchema) as FlexFieldNodeSchema;

package/src/simple-tree/index.ts

@@ -39,8 +39,8 @@ export {
 	type ApplyKind,
 } from "./schemaTypes.js";
 export { SchemaFactory, type ScopedSchemaName } from "./schemaFactory.js";
-export { getFlexNode } from "./proxyBinding.js";
-export { treeNodeApi, type TreeNodeApi, type TreeChangeEvents } from "./treeNodeApi.js";
+export { getFlexNode, tryDisposeTreeNode } from "./proxyBinding.js";
+export { treeNodeApi, type TreeNodeApi } from "./treeNodeApi.js";
 export { toFlexSchema, cursorFromUnhydratedRoot } from "./toFlexSchema.js";
 export type {
 	FieldHasDefaultUnsafe,
@@ -82,7 +82,7 @@ export {
 
 // TreeNode is only type exported, which prevents use of the class object for unsupported use-cases like direct sub-classing and instancof.
 // See docs on TreeNode for more details.
-export type { TreeNode, Unhydrated, InternalTreeNode } from "./types.js";
+export type { TreeChangeEvents, TreeNode, Unhydrated, InternalTreeNode } from "./types.js";
 export {
 	TreeArrayNode,
 	IterableTreeArrayContent,

package/src/simple-tree/leafNodeSchema.ts

@@ -32,7 +32,7 @@ type UnbrandedName<T extends FlexLeafNodeSchema> = T["name"] extends TreeNodeSch
  * @privateRemarks
  * This class refers to the underlying flex tree schema in its constructor, so this class can't be included in the package API.
  */
-class LeafNodeSchema<T extends FlexLeafNodeSchema>
+export class LeafNodeSchema<T extends FlexLeafNodeSchema>
 	implements TreeNodeSchemaNonClass<UnbrandedName<T>, NodeKind.Leaf, TreeValue<T["info"]>>
 {
 	public readonly identifier: UnbrandedName<T>;

package/src/simple-tree/mapNode.ts

@@ -32,7 +32,7 @@ import {
 	typeNameSymbol,
 } from "./schemaTypes.js";
 import { mapTreeFromNodeData } from "./toMapTree.js";
-import { type TreeNode, TreeNodeValid } from "./types.js";
+import { type MostDerivedData, type TreeNode, TreeNodeValid } from "./types.js";
 import { getFlexSchema } from "./toFlexSchema.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -246,7 +246,7 @@ export function mapSchema<
 			);
 		}
 
-		protected static override constructorCached: typeof TreeNodeValid | undefined = undefined;
+		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup<T2>(this: typeof TreeNodeValid<T2>): void {
 			flexSchema = getFlexSchema(this as unknown as TreeNodeSchema) as FlexMapNodeSchema;

package/src/simple-tree/objectNode.ts

@@ -44,7 +44,12 @@ import {
 	FieldKind,
 } from "./schemaTypes.js";
 import { mapTreeFromNodeData } from "./toMapTree.js";
-import { type InternalTreeNode, type TreeNode, TreeNodeValid } from "./types.js";
+import {
+	type InternalTreeNode,
+	type MostDerivedData,
+	type TreeNode,
+	TreeNodeValid,
+} from "./types.js";
 import { type RestrictiveReadonlyRecord, fail, type FlattenKeys } from "../util/index.js";
 import { getFlexSchema } from "./toFlexSchema.js";
 
@@ -187,7 +192,8 @@ function createProxyHandler(
 		set(target, viewKey, value: InsertableContent | undefined, proxy) {
 			const fieldInfo = flexKeyMap.get(viewKey);
 			if (fieldInfo === undefined) {
-				return allowAdditionalProperties ? Reflect.set(target, viewKey, value) : false;
+				// Pass the proxy as the receiver here, so that setters on the prototype receive `proxy` as `this`.
+				return allowAdditionalProperties ? Reflect.set(target, viewKey, value, proxy) : false;
 			}
 
 			const flexNode = getFlexNode(proxy);
@@ -359,7 +365,7 @@ export function objectSchema<
 			);
 		}
 
-		protected static override constructorCached: typeof TreeNodeValid | undefined = undefined;
+		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup<T2>(this: typeof TreeNodeValid<T2>): void {
 			// One time initialization that required knowing the most derived type (from this.constructor) and thus has to be lazy.

package/src/simple-tree/proxies.ts

@@ -20,9 +20,7 @@ import {
 	type FlexFieldSchema,
 	type FlexTreeField,
 	type FlexTreeNode,
-	type FlexTreeNodeEvents,
 	type FlexTreeTypedField,
-	type MapTreeNode,
 	tryGetMapTreeNode,
 	typeNameSymbol,
 	isFlexTreeNode,
@@ -32,7 +30,6 @@ import { type Mutable, fail, isReadonlyArray } from "../util/index.js";
 import { anchorProxy, tryGetFlexNode, tryGetProxy } from "./proxyBinding.js";
 import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
 import type { TreeNode, Unhydrated } from "./types.js";
-import type { Off } from "../events/index.js";
 
 /**
  * Detects if the given 'candidate' is a TreeNode.
@@ -61,10 +58,8 @@ export function getProxyForField(field: FlexTreeField): TreeNode | TreeValue | u
 			FlexFieldSchema<typeof FieldKinds.required | typeof FieldKinds.optional>
 		>,
 	): TreeNode | TreeValue | undefined {
-		const maybeUnboxedContent = flexField.content;
-		return isFlexTreeNode(maybeUnboxedContent)
-			? getOrCreateNodeProxy(maybeUnboxedContent)
-			: maybeUnboxedContent;
+		const maybeContent = flexField.content;
+		return isFlexTreeNode(maybeContent) ? getOrCreateNodeProxy(maybeContent) : maybeContent;
 	}
 	switch (field.schema.kind) {
 		case FieldKinds.required: {
@@ -118,7 +113,6 @@ export function getOrCreateNodeProxy(flexNode: FlexTreeNode): TreeNode | TreeVal
 /** The path of a proxy, relative to the root of the content tree that the proxy belongs to */
 interface RelativeProxyPath {
 	readonly path: UpPath;
-	readonly mapTreeNode: MapTreeNode;
 	readonly proxy: TreeNode;
 }
 
@@ -152,8 +146,8 @@ export function prepareContentForHydration(
 			proxyPaths: [],
 		};
 
-		walkMapTree(content, proxies.rootPath, (p, mapTreeNode, proxy) => {
-			proxies.proxyPaths.push({ path: p, mapTreeNode, proxy });
+		walkMapTree(content, proxies.rootPath, (p, proxy) => {
+			proxies.proxyPaths.push({ path: p, proxy });
 		});
 
 		bindProxies([proxies], forest);
@@ -174,8 +168,8 @@ function prepareArrayContentForHydration(
 			},
 			proxyPaths: [],
 		});
-		walkMapTree(content[i], proxies[i].rootPath, (p, mapTreeNode, proxy) => {
-			proxies[i].proxyPaths.push({ path: p, mapTreeNode, proxy });
+		walkMapTree(content[i], proxies[i].rootPath, (p, proxy) => {
+			proxies[i].proxyPaths.push({ path: p, proxy });
 		});
 	}
 
@@ -185,13 +179,13 @@ function prepareArrayContentForHydration(
 function walkMapTree(
 	mapTree: MapTree,
 	path: UpPath,
-	onVisitTreeNode: (path: UpPath, mapTreeNode: MapTreeNode, treeNode: TreeNode) => void,
+	onVisitTreeNode: (path: UpPath, treeNode: TreeNode) => void,
 ): void {
 	const mapTreeNode = tryGetMapTreeNode(mapTree);
 	if (mapTreeNode !== undefined) {
 		const treeNode = tryGetProxy(mapTreeNode);
 		if (treeNode !== undefined) {
-			onVisitTreeNode(path, mapTreeNode, treeNode);
+			onVisitTreeNode(path, treeNode);
 		}
 	}
 
@@ -217,25 +211,8 @@ function bindProxies(proxies: RootedProxyPaths[], forest: IForestSubscription):
 		let i = 0;
 		const off = forest.on("afterRootFieldCreated", (fieldKey) => {
 			(proxies[i].rootPath as Mutable<UpPath>).parentField = fieldKey;
-			for (const { path, mapTreeNode, proxy } of proxies[i].proxyPaths) {
-				const anchorNode = anchorProxy(forest.anchors, path, proxy);
-				mapTreeNode.forwardEvents({
-					on<K extends keyof FlexTreeNodeEvents>(
-						eventName: K,
-						listener: FlexTreeNodeEvents[K],
-					): Off {
-						switch (eventName) {
-							case "nodeChanged": {
-								return anchorNode.on("childrenChangedAfterBatch", listener);
-							}
-							case "treeChanged": {
-								return anchorNode.on("subtreeChangedAfterBatch", listener);
-							}
-							default:
-								fail("Unexpected event subscription");
-						}
-					},
-				});
+			for (const { path, proxy } of proxies[i].proxyPaths) {
+				anchorProxy(forest.anchors, path, proxy);
 			}
 			if (++i === proxies.length) {
 				off();

package/src/simple-tree/proxyBinding.ts

@@ -29,6 +29,7 @@ import type { TreeNode } from "./types.js";
 // eslint-disable-next-line import/no-internal-modules
 import { makeTree } from "../feature-libraries/flex-tree/lazyNode.js";
 import type { TreeMapNode } from "./mapNode.js";
+import { TreeNodeKernel } from "./treeNodeKernel.js";
 
 // This file contains various maps and helpers for supporting proxy binding (a.k.a. proxy hydration).
 // See ./ProxyBinding.md for a high-level overview of the process.
@@ -185,9 +186,31 @@ function bindProxyToAnchorNode(proxy: TreeNode, anchorNode: AnchorNode): void {
 	proxyToAnchorNode.set(proxy, anchorNode);
 	// However, it's fine for an anchor node to rotate through different proxies when the content at that place in the tree is replaced.
 	anchorNode.slots.set(proxySlot, proxy);
+	getKernel(proxy).hydrate(anchorNode);
 }
 
 /**
  * Given a node's schema, return the corresponding object in the proxy-based API.
  */
 type TypedNode<TSchema extends FlexTreeNodeSchema> = TreeNode & WithType<TSchema["name"]>;
+
+export function createKernel(node: TreeNode): void {
+	treeNodeToKernel.set(node, new TreeNodeKernel(node));
+}
+
+export function getKernel(node: TreeNode): TreeNodeKernel {
+	const kernel = treeNodeToKernel.get(node);
+	assert(kernel !== undefined, 0x9b1 /* Expected tree node to have kernel */);
+	return kernel;
+}
+
+export function tryDisposeTreeNode(anchorNode: AnchorNode): void {
+	const treeNode = anchorNode.slots.get(proxySlot);
+	if (treeNode !== undefined) {
+		const kernel = treeNodeToKernel.get(treeNode);
+		assert(kernel !== undefined, 0x9b2 /* Expected tree node to have kernel */);
+		kernel.dispose();
+	}
+}
+
+const treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();

package/src/simple-tree/schemaFactory.ts

@@ -8,6 +8,8 @@ import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 // which degrades the API-Extractor report quality since API-Extractor can not tell the inline import is the same as the non-inline one.
 // eslint-disable-next-line unused-imports/no-unused-imports
 import type { IFluidHandle as _dummyImport } from "@fluidframework/core-interfaces";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
 import type { TreeValue } from "../core/index.js";
 import { type NodeKeyManager, type Unenforced, isLazy } from "../feature-libraries/index.js";
@@ -20,6 +22,7 @@ import {
 import {
 	booleanSchema,
 	handleSchema,
+	LeafNodeSchema,
 	nullSchema,
 	numberSchema,
 	stringSchema,
@@ -40,7 +43,6 @@ import {
 	getDefaultProvider,
 } from "./schemaTypes.js";
 import { type TreeArrayNode, arraySchema } from "./arrayNode.js";
-import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import {
 	type InsertableObjectFromSchemaRecord,
 	type TreeObjectNode,
@@ -64,6 +66,7 @@ import type {
 	TreeObjectNodeUnsafe,
 } from "./typesUnsafe.js";
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
+import { inPrototypeChain, TreeNodeValid } from "./types.js";
 /**
  * Gets the leaf domain schema compatible with a given {@link TreeValue}.
  */
@@ -161,6 +164,13 @@ export class SchemaFactory<
 	out TScope extends string | undefined = string | undefined,
 	TName extends number | string = string,
 > {
+	/**
+	 * TODO:
+	 * If users of this generate the same name because two different schema with the same identifier were used,
+	 * the second use can get a cache hit, and reference the wrong schema.
+	 * Such usage should probably return a distinct type or error but currently does not.
+	 * The use of markSchemaMostDerived in structuralName at least ensure an error in the case where the collision is from two types extending the same schema factor class.
+	 */
 	private readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();
 
 	/**
@@ -236,7 +246,7 @@ export class SchemaFactory<
 	public readonly handle = handleSchema;
 
 	/**
-	 * Define a {@link TreeNodeSchema} for a {@link TreeObjectNode}.
+	 * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.
 	 *
 	 * @param name - Unique identifier for this schema within this factory's scope.
 	 * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.
@@ -729,6 +739,7 @@ export function structuralName<const T extends string>(
 		const names = allowedTypes.map((t): string => {
 			// Ensure that lazy types (functions) don't slip through here.
 			assert(!isLazy(t), 0x83d /* invalid type provided */);
+			markSchemaMostDerived(t);
 			return t.identifier;
 		});
 		// Ensure name is order independent
@@ -740,3 +751,27 @@ export function structuralName<const T extends string>(
 	}
 	return `${collectionName}<${inner}>`;
 }
+
+/**
+ * Indicates that a schema is the "most derived" version which is allowed to be used, see {@link MostDerivedData}.
+ * Calling helps with error messages about invalid schema usage (using more than one type from single schema factor produced type,
+ * and thus calling this for one than one subclass).
+ * @remarks
+ * Helper for invoking {@link TreeNodeValid.markMostDerived} for any {@link TreeNodeSchema} if it needed.
+ */
+export function markSchemaMostDerived(schema: TreeNodeSchema): void {
+	if (schema instanceof LeafNodeSchema) {
+		return;
+	}
+
+	if (!inPrototypeChain(schema, TreeNodeValid)) {
+		// Use JSON.stringify to quote and escape identifier string.
+		throw new UsageError(
+			`Schema for ${JSON.stringify(
+				schema.identifier,
+			)} does not extend a SchemaFactory generated class. This is invalid.`,
+		);
+	}
+
+	(schema as typeof TreeNodeValid & TreeNodeSchema).markMostDerived();
+}

package/src/simple-tree/schemaTypes.ts

@@ -67,6 +67,41 @@ export interface TreeNodeSchemaNonClass<
  *
  * Using classes in this way allows introducing a named type and a named value at the same time, helping keep the runtime and compile time information together and easy to refer to un a uniform way.
  * Additionally, this works around https://github.com/microsoft/TypeScript/issues/55832 which causes similar patterns with less explicit types to infer "any" in the d.ts file.
+ *
+ * When sub-classing a a `TreeNodeSchemaClass`, some extra rules must be followed:
+ *
+ * - Only ever use a single class from the schema's class hierarchy within a document and its schema.
+ * For example, if using {@link SchemaFactory.object} you can do:
+ * ```typescript
+ * // Recommended "customizable" object schema pattern.
+ * class Good extends schemaFactory.object("A", {
+ * 	exampleField: schemaFactory.number,
+ * }) {
+ * 	public exampleCustomMethod(): void {
+ * 		this.exampleField++;
+ * 	}
+ * }
+ * ```
+ * But should avoid:
+ * ```typescript
+ * // This by itself is ok, and opts into "POJO mode".
+ * const base = schemaFactory.object("A", {});
+ * // This is a bad pattern since it leaves two classes in scope which derive from the same SchemaFactory defined class.
+ * // If both get used, its an error!
+ * class Invalid extends base {}
+ * ```
+ * - Do not modify the constructor input parameter types or values:
+ * ```typescript
+ * class Invalid extends schemaFactory.object("A", {
+ * 	exampleField: schemaFactory.number,
+ * }) {
+ * 	// This Modifies the type of the constructor input.
+ * 	// This is unsupported due to programmatic access to the constructor being used internally.
+ * 	public constructor(a: number) {
+ * 		super({ exampleField: a });
+ * 	}
+ * }
+ * ```
  * @sealed @public
  */
 export interface TreeNodeSchemaClass<
@@ -81,7 +116,7 @@ export interface TreeNodeSchemaClass<
 	 * Constructs an {@link Unhydrated} node with this schema.
 	 * @remarks
 	 * This constructor is also used internally to construct hydrated nodes with a different parameter type.
-	 * Therefor overriding this constructor is not type-safe and is not supported.
+	 * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.
 	 * @sealed
 	 */
 	new (data: TInsertable | InternalTreeNode): Unhydrated<TNode>;

package/src/simple-tree/toFlexSchema.ts

@@ -5,6 +5,7 @@
 
 /* eslint-disable import/no-internal-modules */
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type {
 	ITreeCursorSynchronous,
@@ -75,8 +76,8 @@ export function cursorFromUnhydratedRoot(
 }
 
 interface SchemaInfo {
-	toFlex: () => FlexTreeNodeSchema;
-	original: TreeNodeSchema;
+	readonly toFlex: () => FlexTreeNodeSchema;
+	readonly original: TreeNodeSchema;
 }
 
 type SchemaMap = Map<TreeNodeSchemaIdentifier, SchemaInfo>;
@@ -180,8 +181,8 @@ export function convertNodeSchema(
 	const fromMap = schemaMap.get(brand(schema.identifier));
 	if (fromMap !== undefined) {
 		if (fromMap.original !== schema) {
-			// Use JSON.stringify to quote and escape string.
-			throw new Error(
+			// Use JSON.stringify to quote and escape identifier string.
+			throw new UsageError(
 				`Multiple schema encountered with the identifier ${JSON.stringify(
 					schema.identifier,
 				)}. Remove or rename them to avoid the collision.`,