@fluidframework/tree 2.116.0-416006 → 2.116.1

package/src/shared-tree/treeCheckout.ts

@@ -334,14 +334,11 @@ export function createTreeCheckout(
 		fieldBatchCodec?: FieldBatchCodec;
 		removedRoots?: DetachedFieldIndex;
 		chunkCompressionStrategy?: TreeCompressionStrategy;
-		logger?: TelemetryLoggerExt;
-		breaker?: Breakable;
 		codecOptions?: Partial<CodecWriteOptions>;
 	},
 ): TreeCheckout {
-	const breaker = args?.breaker ?? new Breakable("TreeCheckout", args?.logger);
 	const schema = args?.schema ?? new TreeStoredSchemaRepository();
-	const forest = args?.forest ?? buildForest(breaker, schema);
+	const forest = args?.forest ?? buildForest(new Breakable("TreeCheckout"), schema);
 	const defaultCodecOptions: CodecWriteOptions = {
 		jsonValidator: FormatValidatorNoOp,
 		minVersionForCollab: FluidClientVersion.v2_0,
@@ -380,8 +377,6 @@ export function createTreeCheckout(
 		revisionTagCodec,
 		idCompressor,
 		args?.removedRoots,
-		args?.logger,
-		breaker,
 	);
 }
 
@@ -489,6 +484,31 @@ export function assertValidConstraint(
 export class TreeCheckout implements ITreeCheckout {
 	public disposed = false;
 
+	/**
+	 * Logger for telemetry events related to this checkout.
+	 * @remarks
+	 * This logger is provided by the {@link Breakable} passed to the constructor, and may be `undefined` if no logger was provided.
+	 * See the explanation on {@link Breakable.logger} for why this pattern makes sense.
+	 */
+	private get logger(): TelemetryLoggerExt | undefined {
+		return this.breaker.logger;
+	}
+
+	/**
+	 * The breaker for this checkout.
+	 * @remarks
+	 * As the forest is part of the mutable state of the checkout,
+	 * we want to be broken if it is broken, so we use the forest's breaker as our own.
+	 *
+	 * This does mean that if something goes wrong in the checkout, we break the forest,
+	 * which is not strictly necessary, but may be desirable as if something is wrong with the checkout,
+	 * while the forest might be internally consistent, it likely doesn't contain the correct content
+	 * (since the checkout is keeping it up to date properly anymore).
+	 */
+	public get breaker(): Breakable {
+		return this.forest.breaker;
+	}
+
 	private editLock: EditLock;
 
 	/**
@@ -566,9 +586,6 @@ export class TreeCheckout implements ITreeCheckout {
 		private readonly revisionTagCodec: RevisionTagCodec,
 		private readonly idCompressor: IIdCompressor,
 		private readonly _removedRoots: DetachedFieldIndex = makeDetachedFieldIndex("repair"),
-		/** Optional logger for telemetry. */
-		private readonly logger?: TelemetryLoggerExt,
-		public readonly breaker: Breakable = new Breakable("TreeCheckout", logger),
 		public readonly disposeForksAfterTransaction = true,
 	) {
 		this.#transaction = this.createTransactionStack(branch);
@@ -833,7 +850,7 @@ export class TreeCheckout implements ITreeCheckout {
 							);
 							this.revertibleCommitBranches.set(
 								revision,
-								this.#transaction.activeBranch.fork(commit),
+								this.#transaction.branch.fork(commit),
 							);
 							this.revertibles.set(revision, revertible);
 							return revertible;
@@ -1119,6 +1136,7 @@ export class TreeCheckout implements ITreeCheckout {
 		});
 	};
 
+	@breakingMethod
 	private withCombinedVisitor(fn: (visitor: DeltaVisitor) => void): void {
 		const anchorVisitor = this.forest.anchors.acquireVisitor();
 		const combinedVisitor = combineVisitors([this.forest.acquireVisitor(), anchorVisitor]);
@@ -1132,7 +1150,7 @@ export class TreeCheckout implements ITreeCheckout {
 			if (usageError !== undefined) {
 				throw new UsageError(usageError);
 			}
-			assert(false, 0x911 /* Invalid operation on a disposed TreeCheckout */);
+			fail(0x911 /* Invalid operation on a disposed TreeCheckout */);
 		}
 	}
 
@@ -1189,9 +1207,9 @@ export class TreeCheckout implements ITreeCheckout {
 				}
 
 				const commitToRevert = revertibleBranch.getHead();
-				const activeBranchHead = targetCheckout.#transaction.activeBranch.getHead();
+				const branchHead = targetCheckout.#transaction.branch.getHead();
 
-				if (isAncestor(commitToRevert, activeBranchHead, true) === false) {
+				if (isAncestor(commitToRevert, branchHead, true) === false) {
 					throw new UsageError(
 						"Cannot clone revertible for a commit that is not present on the given branch.",
 					);
@@ -1290,7 +1308,7 @@ export class TreeCheckout implements ITreeCheckout {
 			throw new UsageError("A view cannot be forked while it has a pending transaction.");
 		}
 
-		const branch = this.#transaction.activeBranch.fork();
+		const branch = this.#transaction.branch.fork();
 		const storedSchema = this.storedSchema.clone();
 		const forkBreaker = new Breakable("TreeCheckout", this.logger);
 		const forest = this.forest.clone(storedSchema, forkBreaker);
@@ -1304,8 +1322,6 @@ export class TreeCheckout implements ITreeCheckout {
 			this.revisionTagCodec,
 			this.idCompressor,
 			this._removedRoots.clone(),
-			this.logger,
-			forkBreaker,
 		);
 		this.#events.emit("fork", checkout);
 		return checkout;
@@ -1365,7 +1381,7 @@ export class TreeCheckout implements ITreeCheckout {
 			0xa5d /* Shared branches cannot be rebased onto another branch. */,
 		);
 
-		checkout.#transaction.activeBranch.rebaseOnto(this.#transaction.activeBranch);
+		checkout.#transaction.branch.rebaseOnto(this.#transaction.branch);
 	}
 
 	public rebaseOnto(branch: TreeBranch): void {
@@ -1430,7 +1446,7 @@ export class TreeCheckout implements ITreeCheckout {
 				"Views with an open transaction cannot be merged into another view.",
 			);
 		}
-		this.#transaction.activeBranch.merge(checkout.#transaction.activeBranch);
+		this.#transaction.branch.merge(checkout.#transaction.branch);
 		if (disposeMerged && !checkout.isSharedBranch) {
 			// Dispose the merged checkout unless it is a shared branch.
 			checkout[disposeSymbol]();
@@ -1529,7 +1545,7 @@ export class TreeCheckout implements ITreeCheckout {
 			revisionForInvert,
 		);
 
-		const headCommit = this.#transaction.activeBranch.getHead();
+		const headCommit = this.#transaction.branch.getHead();
 		// Rebase the inverted change onto any commits that occurred after the undoable commits.
 		if (commitToRevert !== headCommit) {
 			// The inverse may be rebased over newer commits which (despite being present in the history)
@@ -1562,7 +1578,7 @@ export class TreeCheckout implements ITreeCheckout {
 		const previousLabelTreeNode = this.labelTreeNode;
 		this.labelTreeNode = labelTree;
 		try {
-			this.#transaction.activeBranch.apply(
+			this.#transaction.branch.apply(
 				change,
 				kind === CommitKind.Default || kind === CommitKind.Redo
 					? CommitKind.Undo
@@ -1704,6 +1720,7 @@ export class TreeCheckout implements ITreeCheckout {
 	public enrich(
 		context: GraphCommit<SharedTreeChange>,
 		changes: readonly TaggedChange<SharedTreeChange>[],
+		forceValidation: boolean,
 	): SharedTreeChange[] {
 		if (!hasSome(changes)) {
 			return [];
@@ -1734,13 +1751,25 @@ export class TreeCheckout implements ITreeCheckout {
 				return makeAnonChange(diff);
 			});
 		}
-		const enriched: SharedTreeChange[] = [];
+		const enrichedChanges: SharedTreeChange[] = [];
 		for (const change of changes) {
-			enriched.push(enricher.enrich(change.change));
-			enricher.enqueueChange(change);
+			const enrichedChange = enricher.enrich(change.change);
+			enrichedChanges.push(enrichedChange);
+			// We could either apply the original or the enriched change: either should allow subsequent changes to be enriched correctly.
+			// We choose to apply the enriched change in order to more closely replicate what a peer will experience (assuming no concurrent changes).
+			// This makes it more likely that we'll detect a bug in the enrichment logic.
+			// Note that enqueueing the change does not guarantee that it will be applied unless `forceValidation` is enabled.
+			enricher.enqueueChange(tagChange(enrichedChange, change.revision));
+		}
+		if (forceValidation) {
+			// Ensure that all changes can be applied successfully.
+			// This is useful for catching bugs in the enrichment logic and in the rebasing logic that may have been involved in producing the changes.
+			// Note that we cannot guarantee that the enriched change will be applied successfully even in the absence of concurrent changes,
+			// because the checkout state we are applying this enriched change to was derived from the state of the checkout, which may be different from that of a peer.
+			enricher.purgeChangeQueue();
 		}
 		enricher[disposeSymbol]();
-		return enriched;
+		return enrichedChanges;
 	}
 
 	public get mainBranch(): SharedTreeBranch<

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

@@ -28,12 +28,16 @@ export class BranchCommitEnricher<TChange> {
 	/**
 	 * Process the given commits for later {@link BranchCommitEnricher.retrieveChange | retrieval}.
 	 * @param commits - The commits to prepare.
+	 * @param forceValidation - Attempt to {@link SharedTreeOptions.validateCommitsOnFirstSubmission|validate} commits before submission in order to fail (throw) locally rather than risk corrupting persisted data.
 	 */
-	public prepareChanges(commits: readonly GraphCommit<TChange>[]): void {
+	public prepareChanges(
+		commits: readonly GraphCommit<TChange>[],
+		forceValidation: boolean,
+	): void {
 		if (hasSome(commits)) {
 			const startingState = commits[0].parent;
 			assert(startingState !== undefined, 0xcc1 /* New commits must have a parent. */);
-			const enrichedCommits = this.enricher.enrich(startingState, commits);
+			const enrichedCommits = this.enricher.enrich(startingState, commits, forceValidation);
 			for (const [index, commit] of commits.entries()) {
 				const enrichedCommit = enrichedCommits[index];
 				assert(enrichedCommit !== undefined, 0xcc2 /* Missing enriched commit. */);

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

@@ -13,7 +13,12 @@ export interface ChangeEnricher<TChange> {
 	 * Runs a batch of change enrichments.
 	 * @param context - The branch head after which the `changes` would apply.
 	 * @param changes - The changes to be enriched.
-	 * @returns The enriched changes.
+	 * @param forceValidation - Attempt to validate enriched changes before submission in order to fail (throw) locally rather than risk corrupting persisted data.
+	 * See {@link SharedTreeOptions.validateCommitsOnFirstSubmission} and {@link SharedTreeOptions.validateRebasedCommitsBeforeResubmission}.
 	 */
-	enrich(context: GraphCommit<TChange>, changes: readonly TaggedChange<TChange>[]): TChange[];
+	enrich(
+		context: GraphCommit<TChange>,
+		changes: readonly TaggedChange<TChange>[],
+		forceValidation: boolean,
+	): TChange[];
 }

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

@@ -37,6 +37,10 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 		 * commits are applied and automatically rebased).
 		 */
 		private readonly enricher: ChangeEnricher<TChange>,
+		/**
+		 * Attempt to {@link SharedTreeOptions.validateRebasedCommitsBeforeResubmission|validate} commits before resubmission in order to fail (throw) locally rather than risk corrupting persisted data.
+		 */
+		private readonly forceValidation: boolean,
 	) {}
 
 	public onCommitSubmitted(commit: GraphCommit<TChange>): void {
@@ -95,6 +99,7 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 		const enriched = this.enricher.enrich(
 			startingState,
 			newCommits.slice(0, staleChanges.length),
+			this.forceValidation,
 		);
 		for (const [index, { pending, newCommit }] of staleChanges.entries()) {
 			const enrichedChange = enriched[index];

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

@@ -351,8 +351,7 @@ export class EditManager<
 		// Only the last trimmed commit, which is the new trunk base, should remain accessible.
 		for (const commit of trimmedCommits.slice(0, -1)) {
 			Reflect.defineProperty(commit, "change", {
-				get: () =>
-					assert(false, 0xa5e /* Should not access 'change' property of an evicted commit */),
+				get: () => fail(0xa5e /* Should not access 'change' property of an evicted commit */),
 			});
 			Reflect.defineProperty(commit, "revision", {
 				get: () =>
@@ -362,8 +361,7 @@ export class EditManager<
 					),
 			});
 			Reflect.defineProperty(commit, "parent", {
-				get: () =>
-					assert(false, 0xa60 /* Should not access 'parent' property of an evicted commit */),
+				get: () => fail(0xa60 /* Should not access 'parent' property of an evicted commit */),
 			});
 		}
 

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+import type { OldestSupportedClientVersion } from "@fluidframework/runtime-definitions/internal";
 import { lowestMinVersionForCollab } from "@fluidframework/runtime-utils/internal";
 
 import {
@@ -132,7 +132,7 @@ export function makeEditManagerCodecBuilder<TChangeset>(): VersionDispatchingCod
  * with the provided change codec tree as a child.
  */
 export function getCodecTreeForEditManagerFormatWithChange(
-	clientVersion: MinimumVersionForCollab,
+	clientVersion: OldestSupportedClientVersion,
 	changeFormat: CodecTree,
 ): CodecTree {
 	const builder = makeEditManagerCodecBuilder();

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

@@ -10,7 +10,7 @@ import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type {
 	IExperimentalIncrementalSummaryContext,
 	ITelemetryContext,
-	MinimumVersionForCollab,
+	OldestSupportedClientVersion,
 } from "@fluidframework/runtime-definitions/internal";
 import type { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
 
@@ -59,7 +59,7 @@ const supportedVersions = new Set<EditManagerSummaryFormatVersion>([
  * Returns the summary version to use as per the given minimum version for collab.
  */
 function minVersionToEditManagerSummaryFormatVersion(
-	version: MinimumVersionForCollab,
+	version: OldestSupportedClientVersion,
 ): EditManagerSummaryFormatVersion {
 	// Currently, version 2 is written which adds metadata blob to the summary.
 	return EditManagerSummaryFormatVersion.v2;
@@ -87,7 +87,7 @@ export class EditManagerSummarizer<TChangeset, TChangeProcessingContext>
 			EditManagerDecodingContext
 		>,
 		private readonly idCompressor: IIdCompressor,
-		minVersionForCollab: MinimumVersionForCollab,
+		minVersionForCollab: OldestSupportedClientVersion,
 		private readonly schemaAndPolicy?: SchemaAndPolicy,
 		/** See {@link IdentifierHealingConfig}. */
 		private readonly healing?: IdentifierHealingConfig,

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

@@ -4,7 +4,7 @@
  */
 
 import type { IIdCompressor } from "@fluidframework/id-compressor";
-import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+import type { OldestSupportedClientVersion } from "@fluidframework/runtime-definitions/internal";
 import { lowestMinVersionForCollab } from "@fluidframework/runtime-utils/internal";
 
 import {
@@ -143,7 +143,7 @@ export function makeMessageCodecBuilder<TChangeset>(): VersionDispatchingCodecBu
 }
 
 export function getCodecTreeForMessageFormatWithChange(
-	clientVersion: MinimumVersionForCollab,
+	clientVersion: OldestSupportedClientVersion,
 	changeFormat: CodecTree,
 ): CodecTree {
 	const builder = makeMessageCodecBuilder();

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { IFluidLoadable, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
+import type { IFluidLoadable } from "@fluidframework/core-interfaces";
 import { assert, fail, unreachableCase } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type { ISnapshotTree } from "@fluidframework/driver-definitions/internal";
@@ -84,6 +84,15 @@ export interface SharedTreeCoreOptionsInternal extends CodecWriteOptions {
 	 * {@inheritDoc SharedTreeOptions.retainHistory}
 	 */
 	readonly retainHistory?: boolean;
+
+	/**
+	 * {@inheritDoc SharedTreeOptions.validateCommitsOnFirstSubmission}
+	 */
+	readonly validateCommitsOnFirstSubmission?: boolean;
+	/**
+	 * {@inheritDoc SharedTreeOptions.validateRebasedCommitsBeforeResubmission}
+	 */
+	readonly validateRebasedCommitsBeforeResubmission?: boolean;
 }
 
 export interface EnrichmentConfig<TChange> {
@@ -152,10 +161,9 @@ export class SharedTreeCore<
 		public readonly sharedObject: IChannelView & IFluidLoadable,
 		public readonly serializer: IFluidSerializer,
 		public readonly submitLocalMessage: (content: unknown, localOpMetadata?: unknown) => void,
-		logger: ITelemetryBaseLogger | undefined,
 		summarizables: readonly Summarizable[],
 		protected readonly changeFamily: ChangeFamily<TEditor, TChange, TChangeProcessingContext>,
-		options: SharedTreeCoreOptionsInternal,
+		private readonly coreOptions: SharedTreeCoreOptionsInternal,
 		changeFormatVersionForEditManager: DependentFormatVersion<EditManagerFormatVersion>,
 		changeFormatVersionForMessage: DependentFormatVersion<MessageFormatVersion>,
 		protected readonly idCompressor: IIdCompressor,
@@ -166,7 +174,7 @@ export class SharedTreeCore<
 	) {
 		super(
 			summarizablesTreeKey,
-			minVersionToSharedTreeSummaryFormatVersion(options.minVersionForCollab),
+			minVersionToSharedTreeSummaryFormatVersion(coreOptions.minVersionForCollab),
 			supportedSharedTreeSummaryFormatVersions,
 			true /* supportPreVersioningFormat */,
 		);
@@ -176,6 +184,8 @@ export class SharedTreeCore<
 			policy: schemaPolicy,
 		};
 
+		const logger = breaker.logger;
+
 		const rebaseLogger = createChildLogger({
 			logger,
 			namespace: "Rebase",
@@ -194,14 +204,14 @@ export class SharedTreeCore<
 			this.mintRevisionTag,
 			(branchId) => this.registerSharedBranch(branchId),
 			rebaseLogger,
-			options.retainHistory ?? false,
+			coreOptions.retainHistory ?? false,
 		);
 
 		this.registerSharedBranch("main");
 
 		const revisionTagCodec = new RevisionTagCodec(idCompressor);
 		const editManagerCodec = makeEditManagerCodecBuilder<TChange>().build({
-			...options,
+			...coreOptions,
 			changeCodecs: this.editManager.changeFamily.codecs,
 			dependentChangeFormatVersion: changeFormatVersionForEditManager,
 			revisionTagCodec,
@@ -211,9 +221,9 @@ export class SharedTreeCore<
 				this.editManager,
 				editManagerCodec,
 				this.idCompressor,
-				options.minVersionForCollab,
+				coreOptions.minVersionForCollab,
 				this.schemaAndPolicy,
-				options.healUnresolvableIdentifiersOnDecode === true
+				coreOptions.healUnresolvableIdentifiersOnDecode === true
 					? { sharedObjectId: sharedObject.id, logger }
 					: undefined,
 			),
@@ -225,7 +235,7 @@ export class SharedTreeCore<
 		);
 
 		this.messageCodec = makeMessageCodecBuilder<TChange>().build({
-			...options,
+			...coreOptions,
 			changeCodecs: changeFamily.codecs,
 			dependentChangeFormatVersion: changeFormatVersionForMessage,
 			revisionTagCodec: new RevisionTagCodec(idCompressor),
@@ -335,7 +345,10 @@ export class SharedTreeCore<
 			if (change.type === "append") {
 				if (this.detachedRevision === undefined) {
 					// Commit enrichment is only necessary for changes that will be submitted as ops, and changes issued while detached are not submitted.
-					this.getCommitEnricher(branchId).prepareChanges(change.newCommits);
+					this.getCommitEnricher(branchId).prepareChanges(
+						change.newCommits,
+						this.coreOptions.validateCommitsOnFirstSubmission ?? false,
+					);
 				}
 
 				for (const commit of change.newCommits) {
@@ -681,7 +694,12 @@ export class SharedTreeCore<
 		assert(!this.enrichers.has(branchId), 0xc6d /* Branch already registered */);
 		this.enrichers.set(branchId, {
 			enricher: commitEnricher,
-			resubmitMachine: resubmitMachine ?? new DefaultResubmitMachine(enricher),
+			resubmitMachine:
+				resubmitMachine ??
+				new DefaultResubmitMachine(
+					enricher,
+					this.coreOptions.validateRebasedCommitsBeforeResubmission ?? false,
+				),
 		});
 	}
 

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

@@ -8,7 +8,7 @@ import type {
 	IExperimentalIncrementalSummaryContext,
 	ISummaryTreeWithStats,
 	ITelemetryContext,
-	MinimumVersionForCollab,
+	OldestSupportedClientVersion,
 } from "@fluidframework/runtime-definitions/internal";
 
 // TODO: Organize this to be adjacent to persisted types.
@@ -115,7 +115,7 @@ export const supportedSharedTreeSummaryFormatVersions =
  * Returns the summary version to use as per the given minimum version for collab.
  */
 export function minVersionToSharedTreeSummaryFormatVersion(
-	version: MinimumVersionForCollab,
+	version: OldestSupportedClientVersion,
 ): SharedTreeSummaryFormatVersion {
 	// Currently, version 2 is written which adds metadata blob to the summary.
 	return SharedTreeSummaryFormatVersion.v2;

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

@@ -313,7 +313,7 @@ export interface SnapshotSchemaCompatibilityOptions {
 	 * Such applications can set this to the oldest version currently deployed,
 	 * then rely on {@link snapshotSchemaCompatibility} to verify that no schema changes are made which would break collaboration with that (or newer) versions.
 	 *
-	 * This is the same approach used by {@link @fluidframework/runtime-definitions#MinimumVersionForCollab}
+	 * This is the same approach used by {@link @fluidframework/runtime-definitions#OldestSupportedClientVersion}
 	 * except that type is specifically for use with the version of the Fluid Framework client packages,
 	 * and this corresponds to whatever versioning scheme is used with {@link SnapshotSchemaCompatibilityOptions.version}.
 	 */

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+import type { OldestSupportedClientVersion } from "@fluidframework/runtime-definitions/internal";
 
 import { FormatValidatorNoOp, type ICodecOptions } from "../../codec/index.js";
 import { schemaCodecBuilder } from "../../feature-libraries/index.js";
@@ -50,7 +50,7 @@ import type { SchemaCompatibilityStatus } from "./tree.js";
  */
 export function extractPersistedSchema(
 	schema: ImplicitFieldSchema,
-	minVersionForCollab: MinimumVersionForCollab,
+	minVersionForCollab: OldestSupportedClientVersion,
 	includeStaged: (upgrade: SchemaUpgrade) => boolean,
 ): JsonCompatible {
 	const stored = toStoredSchema(schema, {

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

@@ -66,7 +66,11 @@ export interface TreeChangeEvents {
 	 * node, or when the node has to be updated due to resolution of a merge conflict
 	 * (for example a previously applied local change might be undone, then reapplied differently or not at all).
 	 *
-	 * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).
+	 * Event ordering: when multiple nodes are directly changed in a single batch,
+	 * events fire in the order nodes were first edited. At each node, `nodeChanged` fires before `treeChanged`.
+	 * When only a leaf node changes, this naturally produces bottom-up ordering
+	 * (leaf events first, then ancestor `treeChanged` propagating up).
+	 * See `treeChangeEventOrdering.spec.ts` for comprehensive ordering tests.
 	 */
 	nodeChanged(unstable?: unknown): void;
 

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

@@ -910,6 +910,21 @@ function createArrayNodeProxy(
 					return proxyTarget.constructor;
 				}
 
+				// If the property is a function on Array.prototype but not on the dispatch target,
+				// return a function that throws a descriptive TypeError when called.
+				if (
+					typeof key === "string" &&
+					!(key in dispatchTarget) &&
+					key in Array.prototype &&
+					typeof (Array.prototype as unknown as Record<string, unknown>)[key] === "function"
+				) {
+					return () => {
+						throw new TypeError(
+							`ArrayNode does not support '${key}'. Use the ArrayNode API (e.g., insertAt, removeAt, moveToIndex, splice).`,
+						);
+					};
+				}
+
 				// Pass the proxy as the receiver here, so that any methods on
 				// the prototype receive `proxy` as `this`.
 				return Reflect.get(dispatchTarget, key, receiver) as unknown;

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

@@ -277,6 +277,27 @@ const handler: ProxyHandler<TreeMapNodeAlpha<any>> = {
 	getPrototypeOf: () => {
 		return Map.prototype;
 	},
+	get: (target, key, receiver) => {
+		const value = Reflect.get(target, key, receiver) as unknown;
+		if (value !== undefined) {
+			return value;
+		}
+		// If the property is a function on Map.prototype but not on the target,
+		// return a function that throws a descriptive TypeError when called.
+		if (
+			typeof key === "string" &&
+			!(key in target) &&
+			key in Map.prototype &&
+			typeof (Map.prototype as unknown as Record<string, unknown>)[key] === "function"
+		) {
+			return () => {
+				throw new TypeError(
+					`MapNode does not support '${key}'. Use the MapNode API (e.g., set, get, delete, keys, values, entries).`,
+				);
+			};
+		}
+		return value;
+	},
 };
 
 abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends TreeNodeValid<
@@ -322,9 +343,9 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 	public has(key: string): boolean {
 		return this.innerNode.tryGetField(brand(key)) !== undefined;
 	}
-	public keys(): IterableIterator<string> {
+	public *keys(): IterableIterator<string> {
 		const node = this.innerNode;
-		return node.keys();
+		yield* node.keys();
 	}
 	public set(key: string, value: InsertableTreeNodeFromImplicitAllowedTypes<T>): this {
 		const kernel = getKernel(this);

package/src/tableSchema.ts

@@ -1590,7 +1590,7 @@ function removeRangeFromArray<TNodeSchema extends ImplicitAllowedTypes>(
  *
  * Also note: these APIs leverage `SharedTree` functionality that was added in version `2.80.0`,
  * which is not compatible with previous versions of this library.
- * To ensure safe collaboration, you will need to configure the {@link @fluidframework/runtime-definitions#MinimumVersionForCollab}
+ * To ensure safe collaboration, you will need to configure the {@link @fluidframework/runtime-definitions#OldestSupportedClientVersion}
  * for the Fluid Runtime and/or `SharedTree` to at least `2.80.0`.
  * To set this minimum version for `SharedTree`, use {@link configuredSharedTreeBeta}.
  *

package/src/treeFactory.ts

@@ -84,7 +84,6 @@ function treeKernelFactory(
 			args.submitLocalMessage,
 			args.lastSequenceNumber,
 			args.initialSequenceNumber,
-			args.logger,
 			args.idCompressor,
 			adjustedOptions,
 		);

package/src/util/breakable.ts

@@ -10,6 +10,10 @@ import { UsageError, type TelemetryLoggerExt } from "@fluidframework/telemetry-u
  * An object which can enter a "broken" state where trying to use it is a UsageError.
  * @remarks
  * Use {@link WithBreakable} to apply this to another object.
+ *
+ * A common pattern is to pass a single breaker to all code which shares mutable state and thus could be put into an invalidate state together.
+ * Thus a breaker often represents a scope for or dependency on mutable state which also forms a scope for fault isolation.
+ * As such a scope can have issues (if it couldn't it would need a breaker), an optional {@link Breakable.logger} is included which can be used to log telemetry within this scope.
  * @sealed
  */
 export class Breakable {
@@ -26,7 +30,11 @@ export class Breakable {
 		 * Optional logger for telemetry.
 		 * @remarks
 		 * When provided, subsystems that have access to a Breakable can use this logger to emit telemetry
-		 * without requiring additional plumbing.
+		 * without requiring additional plumbing of a logger which also corresponds to the same scope/context of this Breakable.
+		 *
+		 * Currently, Breakable itself does not eagerly log breakages into the logger, but we may want to change that in the future.
+		 * Instead it is assumed that fatal errors will result in exceptions logged through other means,
+		 * and the logger here is exposed for users of breaker to log telemetry as desired (for example reporting non-fatal errors or other telemetry).
 		 */
 		public readonly logger?: TelemetryLoggerExt,
 	) {}