@fluidframework/tree 2.10.0-305357 → 2.10.0-307060

package/src/feature-libraries/schema-index/schemaSummarizer.ts

@@ -52,7 +52,7 @@ export class SchemaSummarizer implements Summarizable {
 		collabWindow: CollabWindow,
 	) {
 		this.codec = makeSchemaCodec(options);
-		this.schema.on("afterSchemaChange", () => {
+		this.schema.events.on("afterSchemaChange", () => {
 			// Invalidate the cache, as we need to regenerate the blob if the schema changes
 			// We are assuming that schema changes from remote ops are valid, as we are in a summarization context.
 			this.schemaIndexLastChangedSeq = collabWindow.getCurrentSeq();

package/src/feature-libraries/sequence-field/compose.ts

@@ -582,7 +582,7 @@ export class ComposeQueue {
 		}
 	}
 
-	private dequeueBase(length: number = Infinity): ComposeMarks {
+	private dequeueBase(length: number = Number.POSITIVE_INFINITY): ComposeMarks {
 		const baseMark = this.baseMarks.dequeueUpTo(length);
 		const movedChanges = getMovedChangesFromMark(this.moveEffects, baseMark);
 		if (movedChanges !== undefined) {
@@ -593,7 +593,7 @@ export class ComposeQueue {
 		return { baseMark, newMark };
 	}
 
-	private dequeueNew(length: number = Infinity): ComposeMarks {
+	private dequeueNew(length: number = Number.POSITIVE_INFINITY): ComposeMarks {
 		const newMark = this.newMarks.dequeueUpTo(length);
 		const baseMark = createNoopMark(newMark.count, undefined, getInputCellId(newMark));
 

package/src/feature-libraries/sequence-field/markListFactory.ts

@@ -42,7 +42,7 @@ export class MarkListFactory {
 		if (prev !== undefined && prev.type === mark.type) {
 			const merged = tryMergeMarks(prev, mark);
 			if (merged !== undefined) {
-				this.list.splice(this.list.length - 1, 1, merged);
+				this.list.splice(-1, 1, merged);
 				return;
 			}
 		}

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.10.0-305357";
+export const pkgVersion = "2.10.0-307060";

package/src/shared-tree/schematizingTreeView.ts

@@ -297,7 +297,7 @@ export class SchematizingSimpleTreeView<
 				new HydratedContext(this.rootFieldSchema.allowedTypeSet, view.context),
 			);
 
-			const unregister = this.checkout.storedSchema.on("afterSchemaChange", () => {
+			const unregister = this.checkout.storedSchema.events.on("afterSchemaChange", () => {
 				unregister();
 				this.unregisterCallbacks.delete(unregister);
 				view[disposeSymbol]();
@@ -307,7 +307,7 @@ export class SchematizingSimpleTreeView<
 			this.view = undefined;
 			this.checkout.forest.anchors.slots.delete(SimpleContextSlot);
 
-			const unregister = this.checkout.storedSchema.on("afterSchemaChange", () => {
+			const unregister = this.checkout.storedSchema.events.on("afterSchemaChange", () => {
 				unregister();
 				this.unregisterCallbacks.delete(unregister);
 				this.update();

package/src/shared-tree/treeApi.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { TreeStatus } from "../feature-libraries/index.js";
@@ -464,10 +464,12 @@ function runTransactionInCheckout<TResult>(
 		switch (constraint.type) {
 			case "nodeInDocument": {
 				const node = getOrCreateInnerNode(constraint.node);
-				assert(
-					treeApi.status(constraint.node) === TreeStatus.InDocument,
-					0x90f /* Attempted to apply "nodeExists" constraint when building a transaction, but the node is not in the document. */,
-				);
+				const nodeStatus = treeApi.status(constraint.node);
+				if (nodeStatus !== TreeStatus.InDocument) {
+					throw new UsageError(
+						`Attempted to add a "nodeInDocument" constraint, but the node is not currently in the document. Node status: ${nodeStatus}`,
+					);
+				}
 				checkout.editor.addNodeExistsConstraint(node.anchorNode);
 				break;
 			}
@@ -478,10 +480,10 @@ function runTransactionInCheckout<TResult>(
 	let result: ReturnType<typeof transaction>;
 	try {
 		result = transaction();
-	} catch (e) {
+	} catch (error) {
 		// If the transaction has an unhandled error, abort and rollback the transaction but continue to propagate the error.
 		checkout.transaction.abort();
-		throw e;
+		throw error;
 	}
 
 	if (result === rollback) {

package/src/shared-tree/treeCheckout.ts

@@ -444,15 +444,15 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		private readonly breaker: Breakable = new Breakable("TreeCheckout"),
 	) {
 		// when a transaction is started, take a snapshot of the current state of removed roots
-		_branch.on("transactionStarted", () => {
+		_branch.events.on("transactionStarted", () => {
 			this.removedRootsSnapshots.push(this.removedRoots.clone());
 		});
 		// when a transaction is committed, the latest snapshot of removed roots can be discarded
-		_branch.on("transactionCommitted", () => {
+		_branch.events.on("transactionCommitted", () => {
 			this.removedRootsSnapshots.pop();
 		});
 		// after a transaction is rolled back, revert removed roots back to the latest snapshot
-		_branch.on("transactionRolledBack", () => {
+		_branch.events.on("transactionRolledBack", () => {
 			const snapshot = this.removedRootsSnapshots.pop();
 			assert(snapshot !== undefined, 0x9ae /* a snapshot for removed roots does not exist */);
 			this.removedRoots = snapshot;
@@ -462,7 +462,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		// For example, a bug in the editor might produce a malformed change object and thus applying the change to the forest will throw an error.
 		// In such a case we will crash here, preventing the change from being added to the commit graph, and preventing `afterChange` from firing.
 		// One important consequence of this is that we will not submit the op containing the invalid change, since op submissions happens in response to `afterChange`.
-		_branch.on("beforeChange", (event) => {
+		_branch.events.on("beforeChange", (event) => {
 			if (event.change !== undefined) {
 				const revision =
 					event.type === "replace"
@@ -509,7 +509,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 				}
 			}
 		});
-		_branch.on("afterChange", (event) => {
+		_branch.events.on("afterChange", (event) => {
 			// The following logic allows revertibles to be generated for the change.
 			// Currently only appends (including merges) and transaction commits are supported.
 			if (!_branch.isTransacting()) {
@@ -590,7 +590,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 
 		// When the branch is trimmed, we can garbage collect any repair data whose latest relevant revision is one of the
 		// trimmed revisions.
-		_branch.on("ancestryTrimmed", (revisions) => {
+		_branch.events.on("ancestryTrimmed", (revisions) => {
 			this.withCombinedVisitor((visitor) => {
 				revisions.forEach((revision) => {
 					// get all the roots last created or used by the revision
@@ -653,7 +653,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	}
 
 	public get rootEvents(): Listenable<AnchorSetRootEvents> {
-		return this.forest.anchors;
+		return this.forest.anchors.events;
 	}
 
 	public get editor(): ISharedTreeEditor {

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

@@ -21,7 +21,7 @@ import {
 	tagRollbackInverse,
 	type RebaseStatsWithDuration,
 } from "../core/index.js";
-import { EventEmitter, type Listenable } from "../events/index.js";
+import { createEmitter, type Listenable } from "../events/index.js";
 
 import { TransactionStack } from "./transactionStack.js";
 import { fail } from "../util/index.js";
@@ -175,10 +175,9 @@ export interface BranchTrimmingEvents {
 /**
  * A branch of changes that can be applied to a SharedTree.
  */
-export class SharedTreeBranch<
-	TEditor extends ChangeFamilyEditor,
-	TChange,
-> extends EventEmitter<SharedTreeBranchEvents<TEditor, TChange>> {
+export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
+	readonly #events = createEmitter<SharedTreeBranchEvents<TEditor, TChange>>();
+	public readonly events: Listenable<SharedTreeBranchEvents<TEditor, TChange>> = this.#events;
 	public readonly editor: TEditor;
 	private readonly transactions = new TransactionStack();
 	/**
@@ -222,12 +221,11 @@ export class SharedTreeBranch<
 			keyof RebaseStatsWithDuration
 		>,
 	) {
-		super();
 		this.editor = this.changeFamily.buildEditor(mintRevisionTag, (change) =>
 			this.apply(change),
 		);
 		this.unsubscribeBranchTrimmer = branchTrimmer?.on("ancestryTrimmed", (commit) => {
-			this.emit("ancestryTrimmed", commit);
+			this.#events.emit("ancestryTrimmed", commit);
 		});
 	}
 
@@ -267,9 +265,9 @@ export class SharedTreeBranch<
 			newCommits: [newHead],
 		} as const;
 
-		this.emit("beforeChange", changeEvent);
+		this.#events.emit("beforeChange", changeEvent);
 		this.head = newHead;
-		this.emit("afterChange", changeEvent);
+		this.#events.emit("afterChange", changeEvent);
 		return [taggedChange.change, newHead];
 	}
 
@@ -290,7 +288,7 @@ export class SharedTreeBranch<
 		const onDisposeUnSubscribes: (() => void)[] = [];
 		const onForkUnSubscribe = onForkTransitive(this, (fork) => {
 			forks.add(fork);
-			onDisposeUnSubscribes.push(fork.on("dispose", () => forks.delete(fork)));
+			onDisposeUnSubscribes.push(fork.events.on("dispose", () => forks.delete(fork)));
 		});
 		this.transactions.push(this.head.revision, () => {
 			forks.forEach((fork) => fork.dispose());
@@ -298,7 +296,7 @@ export class SharedTreeBranch<
 			onForkUnSubscribe();
 		});
 		this.editor.enterTransaction();
-		this.emit("transactionStarted", this.transactions.size === 1);
+		this.#events.emit("transactionStarted", this.transactions.size === 1);
 	}
 
 	/**
@@ -315,7 +313,7 @@ export class SharedTreeBranch<
 		const [startCommit, commits] = this.popTransaction();
 		this.editor.exitTransaction();
 
-		this.emit("transactionCommitted", this.transactions.size === 0);
+		this.#events.emit("transactionCommitted", this.transactions.size === 0);
 		if (commits.length === 0) {
 			return undefined;
 		}
@@ -336,9 +334,9 @@ export class SharedTreeBranch<
 			newCommits: [newHead],
 		} as const;
 
-		this.emit("beforeChange", changeEvent);
+		this.#events.emit("beforeChange", changeEvent);
 		this.head = newHead;
-		this.emit("afterChange", changeEvent);
+		this.#events.emit("afterChange", changeEvent);
 		return [commits, newHead];
 	}
 
@@ -356,9 +354,9 @@ export class SharedTreeBranch<
 		const [startCommit, commits] = this.popTransaction();
 		this.editor.exitTransaction();
 
-		this.emit("transactionAborted", this.transactions.size === 0);
+		this.#events.emit("transactionAborted", this.transactions.size === 0);
 		if (commits.length === 0) {
-			this.emit("transactionRolledBack", this.transactions.size === 0);
+			this.#events.emit("transactionRolledBack", this.transactions.size === 0);
 			return [undefined, []];
 		}
 
@@ -384,10 +382,10 @@ export class SharedTreeBranch<
 			removedCommits: commits,
 		} as const;
 
-		this.emit("beforeChange", changeEvent);
+		this.#events.emit("beforeChange", changeEvent);
 		this.head = startCommit;
-		this.emit("afterChange", changeEvent);
-		this.emit("transactionRolledBack", this.transactions.size === 0);
+		this.#events.emit("afterChange", changeEvent);
+		this.#events.emit("transactionRolledBack", this.transactions.size === 0);
 		return [change, commits];
 	}
 
@@ -435,7 +433,7 @@ export class SharedTreeBranch<
 			this.mintRevisionTag,
 			this.branchTrimmer,
 		);
-		this.emit("fork", fork);
+		this.#events.emit("fork", fork);
 		return fork;
 	}
 
@@ -483,9 +481,9 @@ export class SharedTreeBranch<
 			newCommits,
 		} as const;
 
-		this.emit("beforeChange", changeEvent);
+		this.#events.emit("beforeChange", changeEvent);
 		this.head = newSourceHead;
-		this.emit("afterChange", changeEvent);
+		this.#events.emit("afterChange", changeEvent);
 		return rebaseResult;
 	}
 
@@ -529,9 +527,9 @@ export class SharedTreeBranch<
 			newCommits: sourceCommits,
 		} as const;
 
-		this.emit("beforeChange", changeEvent);
+		this.#events.emit("beforeChange", changeEvent);
 		this.head = rebaseResult.newSourceHead;
-		this.emit("afterChange", changeEvent);
+		this.#events.emit("afterChange", changeEvent);
 		return [change, sourceCommits];
 	}
 
@@ -585,7 +583,7 @@ export class SharedTreeBranch<
 		this.unsubscribeBranchTrimmer?.();
 
 		this.disposed = true;
-		this.emit("dispose");
+		this.#events.emit("dispose");
 	}
 
 	private assertNotDisposed(): void {
@@ -594,20 +592,22 @@ export class SharedTreeBranch<
 }
 
 /**
- * Registers an event listener that fires when the given forkable object forks.
+ * Registers an event listener that fires when the given branch forks.
  * The listener will also fire when any of those forks fork, and when those forks of forks fork, and so on.
- * @param forkable - an object that emits an event when it is forked
+ * @param branch - the branch that will be listened to for forks
  * @param onFork - the fork event listener
  * @returns a function which when called will deregister all registrations (including transitive) created by this function.
  * The deregister function has undefined behavior if called more than once.
  */
-export function onForkTransitive<T extends Listenable<{ fork: (t: T) => void }>>(
-	forkable: T,
+// Branches are invariant over TChange
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function onForkTransitive<T extends SharedTreeBranch<ChangeFamilyEditor, any>>(
+	branch: T,
 	onFork: (fork: T) => void,
 ): () => void {
 	const offs: (() => void)[] = [];
 	offs.push(
-		forkable.on("fork", (fork) => {
+		branch.events.on("fork", (fork: T) => {
 			offs.push(onForkTransitive(fork, onFork));
 			onFork(fork);
 		}),

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

@@ -191,7 +191,7 @@ export class EditManager<
 			this.telemetryEventBatcher,
 		);
 
-		this.localBranch.on("afterChange", (event) => {
+		this.localBranch.events.on("afterChange", (event) => {
 			if (event.type === "append") {
 				for (const commit of event.newCommits) {
 					this.localCommits.push(commit);
@@ -223,19 +223,19 @@ export class EditManager<
 	private registerBranch(branch: SharedTreeBranch<TEditor, TChangeset>): void {
 		this.trackBranch(branch);
 		// Whenever the branch is rebased, update our record of its base trunk commit
-		const offBeforeRebase = branch.on("beforeChange", (args) => {
+		const offBeforeRebase = branch.events.on("beforeChange", (args) => {
 			if (args.type === "replace" && getChangeReplaceType(args) === "rebase") {
 				this.untrackBranch(branch);
 			}
 		});
-		const offAfterRebase = branch.on("afterChange", (args) => {
+		const offAfterRebase = branch.events.on("afterChange", (args) => {
 			if (args.type === "replace" && getChangeReplaceType(args) === "rebase") {
 				this.trackBranch(branch);
 				this.trimTrunk();
 			}
 		});
 		// When the branch is disposed, update our branch set and trim the trunk
-		const offDispose = branch.on("dispose", () => {
+		const offDispose = branch.events.on("dispose", () => {
 			this.untrackBranch(branch);
 			this.trimTrunk();
 			offBeforeRebase();

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

@@ -183,16 +183,16 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			this.mintRevisionTag,
 			rebaseLogger,
 		);
-		this.editManager.localBranch.on("transactionStarted", () => {
+		this.editManager.localBranch.events.on("transactionStarted", () => {
 			this.commitEnricher.startNewTransaction();
 		});
-		this.editManager.localBranch.on("transactionAborted", () => {
+		this.editManager.localBranch.events.on("transactionAborted", () => {
 			this.commitEnricher.abortCurrentTransaction();
 		});
-		this.editManager.localBranch.on("transactionCommitted", () => {
+		this.editManager.localBranch.events.on("transactionCommitted", () => {
 			this.commitEnricher.commitCurrentTransaction();
 		});
-		this.editManager.localBranch.on("beforeChange", (change) => {
+		this.editManager.localBranch.events.on("beforeChange", (change) => {
 			// Ensure that any previously prepared commits that have not been sent are purged.
 			this.commitEnricher.purgePreparedCommits();
 			if (this.detachedRevision !== undefined) {
@@ -219,7 +219,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				this.commitEnricher.prepareCommit(change.newCommits[0] ?? oob(), true);
 			}
 		});
-		this.editManager.localBranch.on("afterChange", (change) => {
+		this.editManager.localBranch.events.on("afterChange", (change) => {
 			if (this.getLocalBranch().isTransacting()) {
 				// We do not submit ops for changes that are part of a transaction.
 				return;

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

@@ -73,8 +73,8 @@ 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.
  * @remarks
- * Currently only supports `string` enums.
  * 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.
  * @example
  * ```typescript
@@ -87,7 +87,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * // Define the schema for each member of the enum using a nested scope to group them together.
  * const ModeNodes = adaptEnum(new SchemaFactory(`${schemaFactory.scope}.Mode`), Mode);
  * // Defined the types of the nodes which correspond to this the schema.
- * type ModeNodes = NodeFromSchema<(typeof ModeNodes.schema)[number]>;
+ * type ModeNodes = TreeNodeFromImplicitAllowedTypes<(typeof ModeNodes.schema)>;
  * // An example schema which has an enum as a child.
  * class Parent extends schemaFactory.object("Parent", {
  * 	// adaptEnum's return value has a ".schema" property can be use as an `AllowedTypes` array allowing any of the members of the enum.
@@ -106,8 +106,6 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * }
  * ```
  * @privateRemarks
- * TODO:
- * Extend this to support numeric enums.
  * Maybe provide `SchemaFactory.nested` to ease creating nested scopes?
  * @see {@link enumFromStrings} for a similar function that works on arrays of strings instead of an enum.
  * @alpha
@@ -139,9 +137,12 @@ export function adaptEnum<
 
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	const factoryOut = <TValue extends Values>(value: TValue) => {
-		return new out[inverse.get(value) ?? fail("missing enum value")]() as NodeFromSchema<
-			ReturnType<typeof singletonSchema<TScope, TValue>>
-		>;
+		return new out[
+			inverse.get(value) ?? fail("missing enum value")
+			// "extends unknown" is required here to handle when TValue is an union: each member of the union should be processed independently.
+		]() as TValue extends unknown
+			? NodeFromSchema<ReturnType<typeof singletonSchema<TScope, TValue>>>
+			: never;
 	};
 	const out = factoryOut as typeof factoryOut & TOut & { readonly schema: SchemaArray };
 	for (const [key, value] of Object.entries(members)) {
@@ -176,7 +177,7 @@ export function adaptEnum<
  * ```typescript
  * const schemaFactory = new SchemaFactory("com.myApp");
  * const Mode = enumFromStrings(schemaFactory, ["Fun", "Cool"]);
- * type Mode = NodeFromSchema<(typeof Mode.schema)[number]>;
+ * type Mode = TreeNodeFromImplicitAllowedTypes<typeof Mode.schema>;
  * const nodeFromString: Mode = Mode("Fun");
  * const nodeFromSchema: Mode = new Mode.Fun();
  *
@@ -198,21 +199,32 @@ export function enumFromStrings<
 		throw new UsageError("All members of enums must have distinct names");
 	}
 
-	type TOut = Record<
-		Members[number],
-		ReturnType<typeof singletonSchema<TScope, Members[number]>>
-	>;
-	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-	const factoryOut = <TValue extends Members[number]>(value: TValue) => {
-		return new out[value]() as NodeFromSchema<
-			ReturnType<typeof singletonSchema<TScope, TValue>>
+	type MembersUnion = Members[number];
+
+	// Get all keys of the Members tuple which are numeric strings as union of numbers:
+	type Indexes = Extract<keyof Members, `${number}`> extends `${infer N extends number}`
+		? N
+		: never;
+
+	type TOut = {
+		[Index in Indexes as Members[Index]]: ReturnType<
+			typeof singletonSchema<TScope, Members[Index] & string>
 		>;
 	};
 
-	type SchemaArray = UnionToTuple<TOut[Members[number]]>;
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+	const factoryOut = <TValue extends MembersUnion>(value: TValue) => {
+		// "extends unknown" is required here to handle when TValue is an union: each member of the union should be processed independently.
+		return new recordOut[value]() as TValue extends unknown
+			? NodeFromSchema<ReturnType<typeof singletonSchema<TScope, TValue>>>
+			: never;
+	};
+
+	type SchemaArray = UnionToTuple<MembersUnion extends unknown ? TOut[MembersUnion] : never>;
 	const schemaArray: TreeNodeSchema[] = [];
 
 	const out = factoryOut as typeof factoryOut & TOut & { readonly schema: SchemaArray };
+	const recordOut = out as Record<MembersUnion, new () => unknown>;
 	for (const name of members) {
 		const schema = singletonSchema(factory, name);
 		schemaArray.push(schema);

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

@@ -216,19 +216,45 @@ export class SchemaFactory<
 	private readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();
 
 	/**
-	 * Construct a SchemaFactory with a given scope.
+	 * Construct a SchemaFactory with a given {@link SchemaFactory.scope|scope}.
 	 * @remarks
-	 * There are no restrictions on mixing schema from different schema factories:
-	 * this is encouraged when a single schema references schema from different libraries.
-	 * If each library exporting schema picks its own globally unique scope for its SchemaFactory,
-	 * then all schema an application might depend on, directly or transitively,
-	 * will end up with a unique fully qualified name which is required to refer to it in persisted data and errors.
-	 *
-	 * @param scope - Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.
-	 * Use of [Reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) or a UUIDv4 is recommended to avoid collisions.
-	 * You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.
+	 * There are no restrictions on mixing schema from different schema factories.
+	 * Typically each library will create one or more SchemaFactories and use them to define its schema.
 	 */
-	public constructor(public readonly scope: TScope) {}
+	public constructor(
+		/**
+		 * Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.
+		 *
+		 * @remarks
+		 * Generally each independently developed library
+		 * (possibly a package, but could also be part of a package or multiple packages developed together)
+		 * should get its own unique `scope`.
+		 * Then each schema in the library get a name which is unique within the library.
+		 * The scope and name are joined (with a period) to form the {@link TreeNodeSchemaCore.identifier|schema identifier}.
+		 * Following this pattern allows a single application to depend on multiple libraries which define their own schema, and use them together in a single tree without risk of collisions.
+		 * If a library logically contains sub-libraries with their own schema, they can be given a scope nested inside the parent scope, such as "ParentScope.ChildScope".
+		 *
+		 * To avoid collisions between the scopes of libraries
+		 * it is recommended that the libraries use {@link https://en.wikipedia.org/wiki/Reverse_domain_name_notation | Reverse domain name notation} or a UUIDv4 for their scope.
+		 * If this pattern is followed, application can safely use third party libraries without risk of the schema in them colliding.
+		 *
+		 * You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.
+		 *
+		 * @example
+		 * Fluid Framework follows this pattern, placing the schema for the built in leaf types in the `com.fluidframework.leaf` scope.
+		 * If Fluid Framework publishes more schema in the future, they would be under some other `com.fluidframework` scope.
+		 * This ensures that any schema defined by any other library will not conflict with Fluid Framework's schema
+		 * as long as the library uses the recommended patterns for how to scope its schema..
+		 *
+		 * @example
+		 * A library could generate a random UUIDv4, like `242c4397-49ed-47e6-8dd0-d5c3bc31778b` and use that as the scope.
+		 * Note: do not use this UUID: a new one must be randomly generated when needed to ensure collision resistance.
+		 * ```typescript
+		 * const factory = new SchemaFactory("242c4397-49ed-47e6-8dd0-d5c3bc31778b");
+		 * ```
+		 */
+		public readonly scope: TScope,
+	) {}
 
 	private scoped<Name extends TName | string>(name: Name): ScopedSchemaName<TScope, Name> {
 		return (
@@ -778,6 +804,8 @@ export class SchemaFactory<
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,
 			true,
+			// Setting this (implicitlyConstructable) to true seems to work ok currently, but not for other node kinds.
+			// Supporting this could be fragile and might break other future changes, so it's being kept as false for now.
 			false,
 		);
 
@@ -785,24 +813,29 @@ export class SchemaFactory<
 			ScopedSchemaName<TScope, Name>,
 			NodeKind.Map,
 			TreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
-			{
-				/**
-				 * Iterator for the iterable of content for this node.
-				 * @privateRemarks
-				 * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)
-				 * the following compile error when declaring the recursive schema:
-				 * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`
-				 * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.
-				 *
-				 * If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.
-				 * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.
-				 */
-				[Symbol.iterator](): Iterator<
-					[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]
-				>;
-			},
-			// Ideally this would be included, but doing so breaks recursive types.
-			// | RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,
+			| {
+					/**
+					 * Iterator for the iterable of content for this node.
+					 * @privateRemarks
+					 * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)
+					 * the following compile error when declaring the recursive schema:
+					 * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`
+					 * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.
+					 *
+					 * If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.
+					 * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.
+					 */
+					[Symbol.iterator](): Iterator<
+						[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]
+					>;
+			  }
+			// Ideally this would be
+			// RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,
+			// but doing so breaks recursive types.
+			// Instead we do a less nice version:
+			| {
+					readonly [P in string]: InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
+			  },
 			false,
 			T,
 			undefined

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

@@ -140,7 +140,7 @@ export type ValidateRecursiveSchema<
 				? Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T["info"]>]>
 				: unknown;
 		}[T["kind"]],
-		// ImplicitlyConstructable: recursive types are not implicitly constructable.
+		// ImplicitlyConstructable: recursive types are currently not implicitly constructable.
 		false,
 		// Info: What's passed to the method to create the schema. Constraining these here should be about as effective as if the actual constraints existed on the actual method itself.
 		{

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

@@ -168,7 +168,7 @@ export const treeNodeApi: TreeNodeApi = {
 			case "nodeChanged": {
 				const nodeSchema = kernel.schema;
 				if (isObjectNodeSchema(nodeSchema)) {
-					return kernel.on("childrenChangedAfterBatch", ({ changedFields }) => {
+					return kernel.events.on("childrenChangedAfterBatch", ({ changedFields }) => {
 						const changedProperties = new Set(
 							Array.from(
 								changedFields,
@@ -180,17 +180,17 @@ export const treeNodeApi: TreeNodeApi = {
 						listener({ changedProperties });
 					});
 				} else if (nodeSchema.kind === NodeKind.Array) {
-					return kernel.on("childrenChangedAfterBatch", () => {
+					return kernel.events.on("childrenChangedAfterBatch", () => {
 						listener({ changedProperties: undefined });
 					});
 				} else {
-					return kernel.on("childrenChangedAfterBatch", ({ changedFields }) => {
+					return kernel.events.on("childrenChangedAfterBatch", ({ changedFields }) => {
 						listener({ changedProperties: changedFields });
 					});
 				}
 			}
 			case "treeChanged": {
-				return kernel.on("subtreeChangedAfterBatch", () => listener({}));
+				return kernel.events.on("subtreeChangedAfterBatch", () => listener({}));
 			}
 			default:
 				throw new UsageError(`No event named ${JSON.stringify(eventName)}.`);