@fluidframework/tree 2.83.0 → 2.90.0

package/src/shared-tree/treeCheckout.ts

@@ -55,6 +55,8 @@ import {
 	LeafNodeStoredSchema,
 	diffHistories,
 	type ChangeMetadata,
+	type LabelTree,
+	type TransactionLabels,
 	type ChangeEncodingContext,
 	type ReadOnlyDetachedFieldIndex,
 	makeAnonChange,
@@ -67,9 +69,9 @@ import {
 	buildForest,
 	createNodeIdentifierManager,
 	defaultSchemaPolicy,
+	fieldBatchCodecBuilder,
 	intoDelta,
 	jsonableTreeFromCursor,
-	makeFieldBatchCodec,
 } from "../feature-libraries/index.js";
 import {
 	SquashingTransactionStack,
@@ -108,6 +110,36 @@ import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamil
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 
+/**
+ * Yields all defined (non-`undefined`) labels from a {@link LabelTree}, depth-first.
+ */
+function* collectTreeLabels(node: LabelTree): IterableIterator<unknown> {
+	if (node.label !== undefined) {
+		yield node.label;
+	}
+	for (const child of node.sublabels) {
+		yield* collectTreeLabels(child);
+	}
+}
+
+/**
+ * Builds the labels set for a change event from the label tree.
+ * If the tree exists and contains at least one defined label, returns a set of all
+ * values with the tree attached. Otherwise returns an empty set.
+ */
+function buildLabelsSet(labelTreeNode: LabelTree | undefined): TransactionLabels {
+	const set: Set<unknown> & { tree?: LabelTree } = new Set<unknown>();
+	if (labelTreeNode !== undefined) {
+		for (const value of collectTreeLabels(labelTreeNode)) {
+			set.add(value);
+		}
+		if (set.size > 0) {
+			set.tree = labelTreeNode;
+		}
+	}
+	return set;
+}
+
 /**
  * Events for {@link ITreeCheckout}.
  */
@@ -322,7 +354,7 @@ export function createTreeCheckout(
 		args?.changeFamily ??
 		new SharedTreeChangeFamily(
 			revisionTagCodec,
-			args?.fieldBatchCodec ?? makeFieldBatchCodec(codecOptions),
+			args?.fieldBatchCodec ?? fieldBatchCodecBuilder.build(codecOptions),
 			codecOptions,
 			args?.chunkCompressionStrategy,
 			idCompressor,
@@ -389,12 +421,22 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	private editLock: EditLock;
 
 	/**
-	 * User-defined label associated with the transaction whose commit is currently being produced for this checkout.
+	 * Root of the mutable label tree tracking transaction nesting.
 	 *
 	 * @remarks
-	 * This label is used to implement {@link TreeCheckout.runWithTransactionLabel}.
+	 * The label tree is always isomorphic to the actual transaction tree — every transaction
+	 * (whether labeled or not) gets its own node. To find the "current" (deepest open) node,
+	 * walk down the right side of the tree, stopping at {@link TreeCheckout.mostRecentlyClosedLabelNode}.
+	 *
+	 * Cleared by {@link TreeCheckout.runWithTransactionLabel} after the commit event is emitted.
+	 */
+	private labelTreeNode: LabelTree | undefined;
+
+	/**
+	 * Points to the most recently closed (committed) label node.
+	 * Used by {@link TreeCheckout.currentLabelNode} to stop descending past committed nodes.
 	 */
-	private transactionLabel?: unknown;
+	private mostRecentlyClosedLabelNode: LabelTree | undefined;
 
 	private readonly views = new Set<TreeView<ImplicitFieldSchema>>();
 
@@ -447,6 +489,82 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		this.registerForBranchEvents();
 	}
 
+	/**
+	 * Pushes a new label node for a transaction nesting level.
+	 *
+	 * @param label - The label for this transaction level.
+	 *
+	 * @remarks
+	 * Called at the start of each transaction (including nested ones).
+	 * Creates a new {@link LabelTree} node as a child of the current deepest node (if any),
+	 * or as the root if this is the outermost transaction.
+	 */
+	public pushLabelFrame(label: unknown): void {
+		const node: LabelTree = { label, sublabels: [] };
+		if (this.labelTreeNode === undefined) {
+			this.labelTreeNode = node;
+		} else {
+			const current = this.currentLabelNode();
+			assert(current !== undefined, 0xcdb /* Expected current label node to exist */);
+			current.sublabels.push(node);
+		}
+	}
+
+	/**
+	 * Returns the deepest open node on the right side of the label tree, which corresponds
+	 * to the current (most recently pushed, not yet committed or aborted) transaction.
+	 * Returns `undefined` when {@link TreeCheckout.labelTreeNode} is not set.
+	 */
+	private currentLabelNode(): LabelTree | undefined {
+		if (this.labelTreeNode === undefined) {
+			return undefined;
+		}
+		// Walk down the right spine of the tree. Only one closed node is ever reachable
+		// during this traversal, so a single pointer (mostRecentlyClosedLabelNode) suffices
+		// to stop descending past committed nodes.
+		let node: LabelTree = this.labelTreeNode;
+		while (node.sublabels.length > 0) {
+			const lastChild = node.sublabels[node.sublabels.length - 1];
+			assert(lastChild !== undefined, 0xcdc /* Expected label tree node to have children */);
+			if (lastChild === this.mostRecentlyClosedLabelNode) {
+				break;
+			}
+			node = lastChild;
+		}
+		return node;
+	}
+
+	/**
+	 * Pops the current label frame from the label tree.
+	 * @param aborted - If true, the node is removed from the tree (transaction was aborted).
+	 * If false, the node is kept in the tree but marked as closed (transaction was committed).
+	 */
+	public popLabelFrame(aborted: boolean): void {
+		const node = this.currentLabelNode();
+		if (node === undefined) {
+			return;
+		}
+
+		if (aborted) {
+			if (node === this.labelTreeNode) {
+				this.labelTreeNode = undefined;
+				this.mostRecentlyClosedLabelNode = undefined;
+			} else {
+				// Temporarily mark node as closed so currentLabelNode() returns its parent.
+				this.mostRecentlyClosedLabelNode = node;
+				const parent = this.currentLabelNode();
+				assert(parent !== undefined, 0xcdd /* Expected parent label node to exist */);
+				parent.sublabels.pop();
+				// Point to the parent's new last child (guaranteed closed if it exists),
+				// or undefined if the parent has no more children.
+				const newLastChild = parent.sublabels[parent.sublabels.length - 1];
+				this.mostRecentlyClosedLabelNode = newLastChild;
+			}
+		} else {
+			this.mostRecentlyClosedLabelNode = node;
+		}
+	}
+
 	/**
 	 * Helper method for {@link SchematizingSimpleTreeView.runTransaction} to properly clear transaction labels once the function completes.
 	 *
@@ -463,15 +581,16 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		fn: (label?: TLabel) => TResult,
 		label: TLabel | undefined,
 	): TResult {
-		// If a transaction label is already set, nesting is occurring, so we should not override it.
-		if (this.transactionLabel !== undefined) {
-			return fn(this.transactionLabel as TLabel);
-		}
-		this.transactionLabel = label;
 		try {
-			return fn(this.transactionLabel as TLabel);
+			return fn(label);
 		} finally {
-			this.transactionLabel = undefined;
+			// Only clear the label tree when the outermost transaction has completed.
+			// Inner transactions' commits don't fire the "changed" event, so the label tree
+			// must remain intact until the outermost commit reads it.
+			if (this.transaction.size === 0) {
+				this.labelTreeNode = undefined;
+				this.mostRecentlyClosedLabelNode = undefined;
+			}
 		}
 	}
 
@@ -514,7 +633,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 						if (viewUpdate !== undefined) {
 							this.applyChange(viewUpdate, newHead.revision);
 						}
-						if (!this.transaction.isInProgress()) {
+						if (this.transaction.size === 0) {
 							// The changes in a transaction squash commit have already applied to the checkout and are known to be valid, so we can validate the squash commit automatically.
 							this.validateCommit(newHead);
 						}
@@ -611,7 +730,8 @@ export class TreeCheckout implements ITreeCheckoutFork {
 						} satisfies SerializedChange;
 					},
 					getRevertible: (onDisposed) => getRevertible?.(onDisposed),
-					label: this.transactionLabel,
+					label: this.labelTreeNode?.label,
+					labels: buildLabelsSet(this.labelTreeNode),
 				};
 
 				this.#events.emit("changed", metadata, getRevertible);
@@ -622,6 +742,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			this.#events.emit("changed", {
 				isLocal: false,
 				kind: CommitKind.Default,
+				labels: new Set<unknown>(),
 			});
 		}
 	};
@@ -870,7 +991,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			"The parent branch has already been disposed and can no longer create new branches.",
 		);
 		// Branching after an unfinished transaction would expose the application to a state where its invariants may be violated.
-		if (this.transaction.isInProgress()) {
+		if (this.transaction.size > 0) {
 			throw new UsageError("A view cannot be forked while it has a pending transaction.");
 		}
 
@@ -902,7 +1023,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	): void {
 		// TODO: Dispose old branch, if necessary
 		assert(
-			!this.#transaction.isInProgress(),
+			this.#transaction.size === 0,
 			0xc55 /* Cannot switch branches during a transaction */,
 		);
 		const diff = diffHistories(
@@ -932,12 +1053,12 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		);
 		this.editLock.checkUnlocked("Rebasing");
 
-		if (this.transaction.isInProgress()) {
+		if (this.transaction.size > 0) {
 			throw new UsageError(
 				"Views cannot be rebased onto a view that has a pending transaction.",
 			);
 		}
-		if (checkout.transaction.isInProgress()) {
+		if (checkout.transaction.size > 0) {
 			throw new UsageError("A view cannot be rebased while it has a pending transaction.");
 		}
 
@@ -966,12 +1087,12 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			"The source of the branch merge has been disposed and cannot be merged.",
 		);
 		this.editLock.checkUnlocked("Merging");
-		if (this.transaction.isInProgress()) {
+		if (this.transaction.size > 0) {
 			throw new UsageError(
 				"Views cannot be merged into a view while it has a pending transaction.",
 			);
 		}
-		if (checkout.transaction.isInProgress()) {
+		if (checkout.transaction.size > 0) {
 			throw new UsageError(
 				"Views with an open transaction cannot be merged into another view.",
 			);
@@ -1057,7 +1178,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 
 	private revertRevertible(revision: RevisionTag, kind: CommitKind): RevertMetrics {
 		this.editLock.checkUnlocked("Reverting a commit");
-		if (this.transaction.isInProgress()) {
+		if (this.transaction.size > 0) {
 			throw new UsageError("Undo is not yet supported during transactions.");
 		}
 

package/src/shared-tree/unhydratedTreeContext.ts

@@ -0,0 +1,87 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import type {
+	TreeContextAlpha,
+	TreeBranchAlpha,
+	RunTransactionParams,
+	TransactionResult,
+	TransactionResultExt,
+	WithValue,
+} from "../simple-tree/index.js";
+
+import { assertValidConstraint } from "./schematizingTreeView.js";
+
+/**
+ * A {@link TreeContextAlpha | tree context} that can be used for e.g. unhydrated nodes.
+ */
+export class UnhydratedTreeContext implements TreeContextAlpha {
+	public static instance = new UnhydratedTreeContext();
+	private transactionCount = 0;
+	private constructor() {}
+
+	public isBranch(): this is TreeBranchAlpha {
+		return false;
+	}
+
+	public runTransaction<TValue>(
+		t: () => WithValue<TValue>,
+		params?: RunTransactionParams,
+	): TransactionResultExt<TValue, TValue>;
+	public runTransaction(t: () => void, _params?: RunTransactionParams): TransactionResult;
+	public runTransaction(
+		t: () => WithValue<unknown> | void,
+		params?: RunTransactionParams,
+	): TransactionResultExt<unknown, unknown> | TransactionResult {
+		for (const constraint of params?.preconditions ?? []) {
+			assertValidConstraint(constraint, false);
+		}
+		this.transactionCount += 1;
+		try {
+			return UnhydratedTreeContext.wrapTransactionResult(t());
+		} finally {
+			this.transactionCount -= 1;
+		}
+	}
+
+	public runTransactionAsync<TValue>(
+		t: () => Promise<WithValue<TValue>>,
+		params?: RunTransactionParams,
+	): Promise<TransactionResultExt<TValue, TValue>>;
+	public runTransactionAsync(
+		t: () => Promise<void>,
+		params?: RunTransactionParams,
+	): Promise<TransactionResult>;
+	public async runTransactionAsync(
+		t: () => Promise<WithValue<unknown> | void>,
+		params?: RunTransactionParams,
+	): Promise<TransactionResultExt<unknown, unknown> | TransactionResult> {
+		if (this.transactionCount > 0) {
+			throw new UsageError(
+				"An asynchronous transaction cannot be started while another transaction is already in progress.",
+			);
+		}
+		for (const constraint of params?.preconditions ?? []) {
+			assertValidConstraint(constraint, false);
+		}
+		this.transactionCount += 1;
+		try {
+			return UnhydratedTreeContext.wrapTransactionResult(await t());
+		} finally {
+			this.transactionCount -= 1;
+		}
+	}
+
+	private static wrapTransactionResult<TValue>(
+		value: WithValue<TValue> | void,
+	): TransactionResultExt<TValue, TValue> | TransactionResult {
+		if (value?.value !== undefined) {
+			return { success: true, value: value.value };
+		}
+		return { success: true };
+	}
+}

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

@@ -44,27 +44,14 @@ export enum TransactionResult {
 export interface Transactor {
 	/**
 	 * Start a new transaction.
+	 * @remarks
 	 * If a transaction is already in progress when this new transaction starts, then this transaction will be "nested" inside of it,
 	 * i.e. the outer transaction will still be in progress after this new transaction is committed or aborted.
-	 * @param isAsync - Whether the transaction is asynchronous.
-	 * An error will be thrown if an asynchronous transaction is started while a synchronous transaction is in progress.
-	 *
-	 * @remarks Asynchronous transactions are not supported on the root checkout,
-	 * since it is always kept up-to-date with the latest remote edits and the results of this rebasing (which might invalidate
-	 * the transaction) is not visible to the application author.
-	 * Instead,
-	 *
-	 * 1. fork the root checkout
-	 * 2. run the transaction on the fork
-	 * 3. merge the fork back into the root checkout
-	 *
-	 * @privateRemarks There is currently no enforcement that asynchronous transactions don't happen on the root checkout.
-	 * AB#6488 tracks adding some enforcement to make it more clear to application authors that this is not supported.
 	 */
-	start(isAsync: boolean): void;
+	start(): void;
 	/**
 	 * Close this transaction by squashing its edits and committing them as a single edit.
-	 * If this is the root checkout and there are no ongoing transactions remaining, the squashed edit will be submitted to Fluid.
+	 * @remarks If this is the root checkout and there are no ongoing transactions remaining, the squashed edit will be submitted to Fluid.
 	 */
 	commit(): void;
 	/**
@@ -72,9 +59,10 @@ export interface Transactor {
 	 */
 	abort(): void;
 	/**
-	 * True if there is at least one transaction currently in progress on this view, otherwise false.
+	 * The number of transactions currently in progress, including any nested transactions.
+	 * @remarks This is 0 when no transaction is in progress, 1 when a single transaction is in progress, 2 when a transaction is nested inside another, etc.
 	 */
-	isInProgress(): boolean;
+	size: number;
 	/**
 	 * Provides events for changes in transaction progress.
 	 */
@@ -84,17 +72,17 @@ export interface Transactor {
 export interface TransactionEvents {
 	/**
 	 * Raised just after a transaction has begun.
-	 * @remarks When this event fires, {@link Transactor.isInProgress} will be true because the transaction has already begun.
+	 * @remarks When this event fires, {@link Transactor.size} will be greater than 0 because the transaction has already begun.
 	 */
 	started(): void;
 	/**
 	 * Raised just before a transaction is aborted.
-	 * @remarks When this event fires, {@link Transactor.isInProgress} will still be true because the transaction has not yet ended.
+	 * @remarks When this event fires, {@link Transactor.size} will still be greater than 0 because the transaction has not yet ended.
 	 */
 	aborting(): void;
 	/**
 	 * Raised just before a transaction is committed.
-	 * @remarks When this event fires, {@link Transactor.isInProgress} will still be true because the transaction has not yet ended.
+	 * @remarks When this event fires, {@link Transactor.size} will still be greater than 0 because the transaction has not yet ended.
 	 */
 	committing(): void;
 }
@@ -122,13 +110,13 @@ export interface Callbacks {
 /**
  * A function that will be called when a transaction is pushed to the {@link TransactionStack | stack}.
  * @remarks This function may return other functions that will be called when the transaction is popped from the stack or a nested transaction is pushed onto the stack.
- * This function runs just before the transaction begins, so if this is the beginning of an outermost (not nested) transaction then {@link Transactor.isInProgress} will be false during its execution.
+ * This function runs just before the transaction begins, so if this is the beginning of an outermost (not nested) transaction then {@link Transactor.size} will be 0 during its execution.
  */
 export type OnPush = () => Callbacks | void;
 
 /**
  * A function that will be called when a transaction is popped from the {@link TransactionStack | stack}.
- * @remarks This function runs just after the transaction ends, so if this is the end of an outermost (not nested) transaction then {@link Transactor.isInProgress} will be false during its execution.
+ * @remarks This function runs just after the transaction ends, so if this is the end of an outermost (not nested) transaction then {@link Transactor.size} will be 0 during its execution.
  */
 export type OnPop = (result: TransactionResult) => void;
 
@@ -138,8 +126,6 @@ export type OnPop = (result: TransactionResult) => void;
 interface TransactionStackFrame {
 	/** The callbacks provided when this transaction frame was pushed onto the stack. */
 	readonly callbacks: Callbacks;
-	/** Whether this transaction frame is asynchronous. */
-	readonly isAsync: boolean;
 }
 
 /**
@@ -168,31 +154,25 @@ export class TransactionStack implements Transactor, IDisposable {
 		this.#onPush = onPush;
 	}
 
-	public isInProgress(): boolean {
+	public get size(): number {
 		this.ensureNotDisposed();
-		return this.#stack.length > 0;
+		return this.#stack.length;
 	}
 
-	public start(isAsync: boolean): void {
+	public start(): void {
 		this.ensureNotDisposed();
 		const last = getLast(this.#stack);
-		if (last !== undefined && !last.isAsync && isAsync) {
-			throw new UsageError(
-				"An asynchronous transaction cannot be started while a synchronous transaction is in progress.",
-			);
-		}
 		const onPushCurrent = last === undefined ? this.#onPush : last.callbacks.onPush;
 		const { onPush, onPop } = onPushCurrent?.() ?? {};
 		this.#stack.push({
 			callbacks: { onPop, onPush: onPush ?? onPushCurrent },
-			isAsync,
 		});
 		this.#events.emit("started");
 	}
 
 	public commit(): void {
 		this.ensureNotDisposed();
-		if (!this.isInProgress()) {
+		if (this.size === 0) {
 			throw new UsageError("No transaction to commit");
 		}
 		this.#events.emit("committing");
@@ -201,7 +181,7 @@ export class TransactionStack implements Transactor, IDisposable {
 
 	public abort(): void {
 		this.ensureNotDisposed();
-		if (!this.isInProgress()) {
+		if (this.size === 0) {
 			throw new UsageError("No transaction to abort");
 		}
 		this.#events.emit("aborting");
@@ -210,7 +190,7 @@ export class TransactionStack implements Transactor, IDisposable {
 
 	public dispose(): void {
 		this.ensureNotDisposed();
-		while (this.isInProgress()) {
+		while (this.size > 0) {
 			this.abort();
 		}
 		this.#disposed = true;
@@ -225,7 +205,7 @@ export class TransactionStack implements Transactor, IDisposable {
 
 /**
  * A function that will be called when a transaction is popped from the {@link SquashingTransactionStack | stack}.
- * @remarks This function runs just after the transaction ends, so if this is the end of an outermost (not nested) transaction then {@link Transactor.isInProgress} will be false during its execution.
+ * @remarks This function runs just after the transaction ends, so if this is the end of an outermost (not nested) transaction then {@link Transactor.size} will be 0 during its execution.
  * @param result - The result of the transaction.
  * @param viewUpdate - The change that needs to be applied to the view to keep it up-to-date with the branch after the transaction ends.
  * This is needed in asynchronous transactions where new commits have been added to the branch while the transaction was in progress.
@@ -328,7 +308,7 @@ export class SquashingTransactionStack<
 
 				// Invoked when an outer transaction ends
 				const onOuterTransactionPop: OnPop = (result) => {
-					assert(!this.isInProgress(), 0xcae /* The outer transaction should be ending */);
+					assert(this.size === 0, 0xcae /* The outer transaction should be ending */);
 					transactionBranch.editor.exitTransaction();
 
 					const sourcePath: GraphCommit<TChange>[] = [];

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

@@ -147,6 +147,10 @@ export interface ITreeViewConfiguration<
 > extends ITreeConfigurationOptions {
 	/**
 	 * The schema which the application wants to view the tree with.
+	 * @remarks
+	 * Use {@link SchemaFactory} to construct the schema.
+	 * Changes to this schema between different versions have important compatibility implications.
+	 * See the {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution | documentation on schema evolution} for more details.
 	 */
 	readonly schema: TSchema;
 }

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

@@ -5,13 +5,13 @@
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { TreeIndexKey } from "../../feature-libraries/index.js";
+import type { TreeIndex } from "../../feature-libraries/index.js";
 import type { TreeNode } from "../core/index.js";
 import { FieldKind, type ImplicitFieldSchema } from "../fieldSchema.js";
 import { ObjectNodeSchema } from "../node-kinds/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
 
-import { createSimpleTreeIndex, type SimpleTreeIndex } from "./simpleTreeIndex.js";
+import { createTreeIndex, type TreeIndexKey } from "./simpleTreeIndex.js";
 import type { TreeView } from "./tree.js";
 
 /**
@@ -19,7 +19,7 @@ import type { TreeView } from "./tree.js";
  *
  * @alpha
  */
-export type IdentifierIndex = SimpleTreeIndex<string, TreeNode>;
+export type IdentifierIndex = TreeIndex<string, TreeNode>;
 
 function isStringKey(key: TreeIndexKey): key is string {
 	return typeof key === "string";
@@ -49,7 +49,7 @@ export function createIdentifierIndex<TSchema extends ImplicitFieldSchema>(
 		},
 	});
 
-	return createSimpleTreeIndex(
+	return createTreeIndex(
 		view,
 		(schemus) => identifierFields.get(schemus.identifier),
 		(nodes) => {

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

@@ -22,6 +22,7 @@ export type {
 	TreeBranch,
 	TreeBranchAlpha,
 	TreeBranchEvents,
+	TreeContextAlpha,
 	ITreeAlpha,
 } from "./tree.js";
 export { asTreeViewAlpha } from "./tree.js";
@@ -141,7 +142,7 @@ export {
 	TreeBeta,
 	type TreeChangeEventsBeta,
 } from "./treeBeta.js";
-export { createSimpleTreeIndex, type SimpleTreeIndex } from "./simpleTreeIndex.js";
+export { createTreeIndex, type TreeIndexKey } from "./simpleTreeIndex.js";
 export {
 	createIdentifierIndex,
 	type IdentifierIndex,
@@ -164,6 +165,7 @@ export {
 	type TransactionResultExt,
 	type TransactionResultSuccess,
 	type TransactionResultFailed,
+	type WithValue,
 	rollback,
 } from "./transactionTypes.js";
 

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

@@ -226,12 +226,13 @@ export const SchemaFactory_base = classWithStatics(schemaStaticsPublic);
  * @remarks
  * For details related to inputting data constrained by schema (including via assignment), and how non-exact schema types are handled in general refer to {@link Input}.
  * For information about recursive schema support, see methods postfixed with "recursive" and {@link ValidateRecursiveSchema}.
- * To apply schema defined with this factory to a tree, see {@link ViewableTree.viewWith} and {@link TreeViewConfiguration}.
+ * To apply schema defined with this factory to a tree, see {@link TreeViewConfiguration} and {@link ViewableTree.viewWith}.
+ * See the {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution | documentation on schema evolution} for how to handle changes to schema over time.
  *
  * All schema produced by this factory get a {@link TreeNodeSchemaCore.identifier|unique identifier} by combining the {@link SchemaFactory.scope} with the schema's `Name`.
  * The `Name` part may be explicitly provided as a parameter, or inferred as a structural combination of the provided types.
  * The APIs which use this second approach, structural naming, also deduplicate all equivalent calls.
- * Therefor two calls to `array(allowedTypes)` with the same allowedTypes will return the same {@link TreeNodeSchema} instance.
+ * Therefore two calls to `array(allowedTypes)` with the same allowedTypes will return the same {@link TreeNodeSchema} instance.
  * On the other hand, two calls to `array(name, allowedTypes)` will always return different {@link TreeNodeSchema} instances
  * and it is an error to use both in the same tree (since their identifiers are not unique).
  *