@fluidframework/tree 2.115.0 → 2.116.0

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,
 	) {}

package/src/util/compressedIds.ts

@@ -3,7 +3,6 @@
  * Licensed under the MIT License.
  */
 
-import { LogLevel, type ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import type {
 	IIdCompressor,
@@ -12,6 +11,7 @@ import type {
 	SessionSpaceCompressedId,
 } from "@fluidframework/id-compressor";
 import { isFinalId, isStableId } from "@fluidframework/id-compressor/internal";
+import type { TelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 import { v5 as uuidV5 } from "uuid";
 
 /**
@@ -172,7 +172,7 @@ export interface IdentifierHealingConfig {
 	 * Optional logger used by {@link forceDecodeEncodedIdWithoutSession} to record telemetry
 	 * when the heal-on-decode recovery path is taken (a non-final identifier is healed).
 	 */
-	readonly logger?: ITelemetryBaseLogger;
+	readonly logger?: TelemetryLoggerExt;
 }
 
 /**
@@ -207,17 +207,11 @@ export function forceDecodeEncodedIdWithoutSession(
 	// `id` is a non-final op-space compressed id.
 	if (healing !== undefined) {
 		const healed = uuidV5(`${healing.sharedObjectId}|${id}`, healingNamespace);
-		healing.logger?.send(
-			{
-				category: "generic",
-				eventName: "HealUnresolvableIdentifierOnDecode",
-			},
-			// This telemetry should be very low-volume (and possibly never happen at all),
-			// as should only occur when loading documents that were corrupted by a now fixed bug and have not been re-summarized since healing was added.
-			// It is useful for monitoring and diagnosing for this to be reported in the same cases in which the error case would be reported,
-			// which is the essential level.
-			LogLevel.essential,
-		);
+		// This telemetry should be very low-volume (and possibly never happen at all),
+		// as should only occur when loading documents that were corrupted by a now fixed bug and have not been re-summarized since healing was added.
+		// It is useful for monitoring and diagnosing for this to be reported in the same cases in which the error case would be reported,
+		// which is the essential level.
+		healing.logger?.sendTelemetryEvent({ eventName: "HealUnresolvableIdentifierOnDecode" });
 		return healed;
 	}
 	throw new Error(