@fluid-experimental/tree 0.59.4001 → 1.1.0-75972

package/src/SharedTree.ts

@@ -27,7 +27,15 @@ import { ChildLogger, ITelemetryLoggerPropertyBags, PerformanceEvent } from '@fl
 import { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
 import { assert, assertNotUndefined, fail, copyPropertyIfDefined, noop } from './Common';
 import { EditHandle, EditLog, getNumberOfHandlesFromEditLogSummary, OrderedEditSet } from './EditLog';
-import { EditId, NodeId, StableNodeId, DetachedSequenceId, OpSpaceNodeId, isDetachedSequenceId } from './Identifiers';
+import {
+	EditId,
+	NodeId,
+	StableNodeId,
+	DetachedSequenceId,
+	OpSpaceNodeId,
+	isDetachedSequenceId,
+	AttributionId,
+} from './Identifiers';
 import { initialTree } from './InitialTree';
 import {
 	CachingLogViewer,
@@ -88,6 +96,75 @@ import { TransactionInternal } from './TransactionInternal';
 import { IdCompressor, createSessionId } from './id-compressor';
 import { convertEditIds } from './IdConversion';
 import { MutableStringInterner } from './StringInterner';
+import { nilUuid } from './UuidUtilities';
+
+/**
+ * The write format and associated options used to construct a `SharedTree`
+ * @public
+ */
+export type SharedTreeArgs<WF extends WriteFormat = WriteFormat> = [writeFormat: WF, options?: SharedTreeOptions<WF>];
+
+/**
+ * The type of shared tree options for a given write format
+ * @public
+ */
+export type SharedTreeOptions<
+	WF extends WriteFormat,
+	HistoryCompatibility extends 'Forwards' | 'None' = 'Forwards'
+> = Omit<
+	WF extends WriteFormat.v0_0_2
+		? SharedTreeOptions_0_0_2
+		: WF extends WriteFormat.v0_1_1
+		? SharedTreeOptions_0_1_1
+		: never,
+	HistoryCompatibility extends 'Forwards' ? 'summarizeHistory' : never
+>;
+
+/**
+ * Configuration options for a SharedTree with write format 0.0.2
+ * @public
+ */
+export interface SharedTreeOptions_0_0_2 {
+	/**
+	 * Determines if the history is included in summaries.
+	 *
+	 * Warning: enabling history summarization incurs a permanent cost in the document. It is not possible to disable history summarization
+	 * later once it has been enabled, and thus the history cannot be safely deleted.
+	 *
+	 * On 0.1.1 documents, due to current code limitations, this parameter is only impactful for newly created documents.
+	 * `SharedTree`s which load existing documents will summarize history if and only if the loaded summary included history.
+	 *
+	 * The technical limitations here relate to clients with mixed versions collaborating.
+	 * In the future we may allow modification of whether or not a particular document saves history, but only via a consensus mechanism.
+	 * See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
+	 * See docs/Breaking-Change-Migration for more details on the consensus scheme.
+	 */
+	summarizeHistory?: boolean;
+}
+
+/**
+ * Configuration options for a SharedTree with write format 0.1.1
+ * @public
+ */
+export interface SharedTreeOptions_0_1_1 {
+	/**
+	 * Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
+	 *
+	 * Warning: enabling history summarization incurs a permanent cost in the document. It is not possible to disable history summarization
+	 * later once it has been enabled, and thus the history cannot be safely deleted.
+	 *
+	 * On 0.1.1 documents, due to current code limitations, this parameter is only impactful for newly created documents.
+	 * `SharedTree`s which load existing documents will summarize history if and only if the loaded summary included history.
+	 *
+	 * The technical limitations here relate to clients with mixed versions collaborating.
+	 * In the future we may allow modification of whether or not a particular document saves history, but only via a consensus mechanism.
+	 * See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
+	 * See docs/Breaking-Change-Migration for more details on the consensus scheme.
+	 */
+	summarizeHistory?: false | { uploadEditChunks: boolean };
+	/** a UUID that identifies the user of this tree; all node IDs generated by this tree will be associated with this UUID */
+	attributionId?: AttributionId;
+}
 
 /**
  * Factory for SharedTree.
@@ -109,20 +186,20 @@ export class SharedTreeFactory implements IChannelFactory {
 		packageVersion: '0.1',
 	};
 
+	private readonly args: SharedTreeArgs;
+
 	/**
 	 * Get a factory for SharedTree to register with the data store.
 	 * @param writeFormat - Determines the format version the SharedTree will write ops and summaries in. See [the write format
 	 * documentation](../docs/Write-Format.md) for more information.
-	 * @param summarizeHistory - Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
-	 * See the [breaking change migration documentation](docs/Breaking-Change-Migration) for more details on this scheme.
-	 * @param expensiveValidation - Enables expensive asserts on SharedTree.
+	 * @param options - Configuration options for this tree
 	 * @returns A factory that creates `SharedTree`s and loads them from storage.
 	 */
-	constructor(
-		private readonly writeFormat: WriteFormat,
-		private readonly summarizeHistory: false | { uploadEditChunks: boolean } = false,
-		private expensiveValidation = false
-	) {}
+	constructor(...args: SharedTreeArgs<WriteFormat.v0_0_2>);
+	constructor(...args: SharedTreeArgs<WriteFormat.v0_1_1>);
+	constructor(...args: SharedTreeArgs) {
+		this.args = args;
+	}
 
 	/**
 	 * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory."type"}
@@ -157,22 +234,22 @@ export class SharedTreeFactory implements IChannelFactory {
 	 * @param runtime - data store runtime that owns the new SharedTree
 	 * @param id - optional name for the SharedTree
 	 */
-	public create(runtime: IFluidDataStoreRuntime, id: string, expensiveValidation: boolean = false): SharedTree {
-		this.expensiveValidation = expensiveValidation;
+	public create(runtime: IFluidDataStoreRuntime, id: string): SharedTree {
 		const sharedTree = this.createSharedTree(runtime, id);
 		sharedTree.initializeLocal();
 		return sharedTree;
 	}
 
 	private createSharedTree(runtime: IFluidDataStoreRuntime, id: string): SharedTree {
-		const sharedTree = new SharedTree(
-			runtime,
-			id,
-			this.writeFormat,
-			this.summarizeHistory,
-			this.expensiveValidation
-		);
-		return sharedTree;
+		const [writeFormat] = this.args;
+		switch (writeFormat) {
+			case WriteFormat.v0_0_2:
+				return new SharedTree(runtime, id, ...(this.args as SharedTreeArgs<WriteFormat.v0_0_2>));
+			case WriteFormat.v0_1_1:
+				return new SharedTree(runtime, id, ...(this.args as SharedTreeArgs<WriteFormat.v0_1_1>));
+			default:
+				fail('Unknown write format');
+		}
 	}
 }
 
@@ -281,35 +358,56 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 
 	/**
 	 * Get a factory for SharedTree to register with the data store.
-	 * @param summarizeHistory - Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
-	 *
-	 * On 0.1.1 documents, due to current code limitations, this parameter is only impactful for newly created documents.
-	 * `SharedTree`s which load existing documents will summarize history if and only if the loaded summary included history.
-	 *
-	 * The technical limitations here relate to clients with mixed versions collaborating.
-	 * In the future we may allow modification of whether or not a particular document saves history, but only via a consensus mechanism.
-	 * See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
-	 * See docs/Breaking-Change-Migration for more details on the consensus scheme.
 	 * @param writeFormat - Determines the format version the SharedTree will write ops and summaries in.
 	 * This format may be updated to a newer (supported) version at runtime if a collaborating shared-tree
 	 * that was initialized with a newer write version connects to the session. Care must be taken when changing this value,
 	 * as a staged rollout must of occurred such that all collaborating clients must have the code to read at least the version
 	 * written.
 	 * See [the write format documentation](../docs/Write-Format.md) for more information.
+	 * @param options - Configuration options for this tree
 	 * @returns A factory that creates `SharedTree`s and loads them from storage.
 	 */
-	public static getFactory(
-		writeFormat: WriteFormat,
-		summarizeHistory: false | { uploadEditChunks: boolean } = false
-	): SharedTreeFactory {
+	public static getFactory(...args: SharedTreeArgs<WriteFormat.v0_0_2>): SharedTreeFactory;
+
+	public static getFactory(...args: SharedTreeArgs<WriteFormat.v0_1_1>): SharedTreeFactory;
+
+	public static getFactory(...args: SharedTreeArgs): SharedTreeFactory {
+		const [writeFormat] = args;
 		// 	On 0.1.1 documents, due to current code limitations, all clients MUST agree on the value of `summarizeHistory`.
 		//  Note that this means staged rollout changing this value should not be attempted.
 		//  It is possible to update shared-tree to correctly handle such a staged rollout, but that hasn't been implemented.
 		//  See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
-		return new SharedTreeFactory(writeFormat, summarizeHistory);
+		switch (writeFormat) {
+			case WriteFormat.v0_0_2:
+				return new SharedTreeFactory(...(args as SharedTreeArgs<WriteFormat.v0_0_2>));
+			case WriteFormat.v0_1_1:
+				return new SharedTreeFactory(...(args as SharedTreeArgs<WriteFormat.v0_1_1>));
+			default:
+				fail('Unknown write format');
+		}
 	}
 
-	private idCompressor: IdCompressor = new IdCompressor(createSessionId(), reservedIdCount);
+	/**
+	 * The UUID used for attribution of nodes created by this SharedTree. All shared trees with a write format of 0.1.1 or
+	 * greater have a unique attribution ID which may be configured in the constructor. All other shared trees (i.e. those
+	 * with a write format of 0.0.2) use the nil UUID as their attribution ID.
+	 * @public
+	 */
+	public get attributionId(): AttributionId {
+		switch (this.writeFormat) {
+			case WriteFormat.v0_0_2:
+				return nilUuid;
+			default: {
+				const { attributionId } = this.idCompressor;
+				if (attributionId === ghostSessionId) {
+					return nilUuid;
+				}
+				return attributionId;
+			}
+		}
+	}
+
+	private idCompressor: IdCompressor;
 	private readonly idNormalizer: NodeIdNormalizer<OpSpaceNodeId> & { tree: SharedTree } = {
 		tree: this,
 		get localSessionId() {
@@ -375,25 +473,44 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 	private summarizeHistory: boolean;
 	private uploadEditChunks: boolean;
 
+	private getHistoryPolicy(options: SharedTreeOptions<WriteFormat, 'Forwards' | 'None'>): {
+		summarizeHistory: boolean;
+		uploadEditChunks: boolean;
+	} {
+		const noCompatOptions = options as SharedTreeOptions<WriteFormat, 'None'>;
+		return typeof noCompatOptions.summarizeHistory === 'object'
+			? {
+					summarizeHistory: true,
+					uploadEditChunks: noCompatOptions.summarizeHistory.uploadEditChunks,
+			  }
+			: {
+					summarizeHistory: noCompatOptions.summarizeHistory ?? false,
+					uploadEditChunks: false,
+			  };
+	}
+
 	/**
-	 * Create a new SharedTreeFactory.
+	 * Create a new SharedTree.
 	 * @param runtime - The runtime the SharedTree will be associated with
 	 * @param id - Unique ID for the SharedTree
 	 * @param writeFormat - Determines the format version the SharedTree will write ops and summaries in. See [the write format
 	 * documentation](../docs/Write-Format.md) for more information.
-	 * @param summarizeHistory - Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
-	 * @param expensiveValidation - Enable expensive asserts.
+	 * @param options - Configuration options for this tree
 	 */
+	public constructor(runtime: IFluidDataStoreRuntime, id: string, ...args: SharedTreeArgs<WriteFormat.v0_0_2>);
+
+	public constructor(runtime: IFluidDataStoreRuntime, id: string, ...args: SharedTreeArgs<WriteFormat.v0_1_1>);
+
 	public constructor(
 		runtime: IFluidDataStoreRuntime,
 		id: string,
 		private writeFormat: WriteFormat,
-		summarizeHistory: false | { uploadEditChunks: boolean } = false,
-		private readonly expensiveValidation = false
+		options: SharedTreeOptions<typeof writeFormat> = {}
 	) {
-		super(id, runtime, SharedTreeFactory.Attributes);
-		this.summarizeHistory = summarizeHistory === false ? false : true;
-		this.uploadEditChunks = summarizeHistory === false ? false : summarizeHistory.uploadEditChunks;
+		super(id, runtime, SharedTreeFactory.Attributes, 'fluid_sharedTree_');
+		const historyPolicy = this.getHistoryPolicy(options);
+		this.summarizeHistory = historyPolicy.summarizeHistory;
+		this.uploadEditChunks = historyPolicy.uploadEditChunks;
 
 		// This code is somewhat duplicated from OldestClientObserver because it currently depends on the container runtime
 		// which SharedTree does not have access to.
@@ -412,13 +529,15 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 			sharedTreeTelemetryProperties
 		);
 
+		const attributionId = (options as SharedTreeOptions<WriteFormat.v0_1_1>).attributionId;
+		this.idCompressor = new IdCompressor(createSessionId(), reservedIdCount, attributionId, this.logger);
 		const { editLog, cachingLogViewer } = this.initializeNewEditLogFromSummary(
 			{
 				editChunks: [],
 				editIds: [],
 			},
 			undefined,
-			this.idCompressor, // TODO: Attribution info
+			this.idCompressor,
 			this.processEditResult,
 			this.processSequencedEditResult,
 			WriteFormat.v0_1_1
@@ -429,6 +548,11 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 		this.encoder_0_1_1 = new SharedTreeEncoder_0_1_1(this.summarizeHistory);
 	}
 
+	/**
+	 * The write format version currently used by this `SharedTree`. This is always initialized to the write format
+	 * passed to the tree's constructor, but it may automatically upgrade over time (e.g. when connected to another
+	 * SharedTree with a higher write format, or when loading a summary with a higher write format).
+	 */
 	public getWriteFormat(): WriteFormat {
 		return this.writeFormat;
 	}
@@ -555,6 +679,26 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 		return this.idCompressor.tryRecompress(id) as NodeId | undefined;
 	}
 
+	/**
+	 * Returns the attribution ID associated with the SharedTree that generated the given node ID. This is generally only useful for clients
+	 * with a write format of 0.1.1 or greater since older clients cannot be given an attribution ID and will always use the default
+	 * `attributionId` of the tree.
+	 * @public
+	 */
+	public attributeNodeId(id: NodeId): AttributionId {
+		switch (this.writeFormat) {
+			case WriteFormat.v0_0_2:
+				return nilUuid;
+			default: {
+				const attributionId = this.idCompressor.attributeId(id);
+				if (attributionId === ghostSessionId) {
+					return nilUuid;
+				}
+				return attributionId;
+			}
+		}
+	}
+
 	/**
 	 * @returns the edit history of the tree.
 	 * @public
@@ -744,7 +888,10 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 		let convertedSummary: SummaryContents;
 		switch (loadedSummaryVersion) {
 			case WriteFormat.v0_0_2:
-				convertedSummary = this.encoder_0_0_2.decodeSummary(summary as SharedTreeSummary_0_0_2);
+				convertedSummary = this.encoder_0_0_2.decodeSummary(
+					summary as SharedTreeSummary_0_0_2,
+					this.attributionId
+				);
 				break;
 			case WriteFormat.v0_1_1: {
 				const typedSummary = summary as SharedTreeSummary;
@@ -756,7 +903,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 					this.encoder_0_1_1 = new SharedTreeEncoder_0_1_1(this.summarizeHistory);
 				}
 
-				convertedSummary = this.encoder_0_1_1.decodeSummary(summary as SharedTreeSummary); // TODO:#461: pass attribution info
+				convertedSummary = this.encoder_0_1_1.decodeSummary(summary as SharedTreeSummary, this.attributionId);
 				break;
 			}
 			default:
@@ -944,9 +1091,12 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 		};
 		this.cachingLogViewer.setMinimumSequenceNumber(typedMessage.minimumSequenceNumber);
 		const op = typedMessage.contents;
+		if (op.version === undefined) {
+			// Back-compat: some legacy documents may contain trailing ops with an unstamped version; normalize them.
+			(op as { version: WriteFormat | undefined }).version = WriteFormat.v0_0_2;
+		}
 		const { type, version } = op;
-		const resolvedVersion = version ?? WriteFormat.v0_0_2;
-		const sameVersion = resolvedVersion === this.writeFormat;
+		const sameVersion = version === this.writeFormat;
 
 		// Edit and handle ops should only be processed if they're the same version as the tree write version.
 		// Update ops should only be processed if they're not the same version.
@@ -979,7 +1129,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 			}
 		} else if (type === SharedTreeOpType.Update) {
 			this.processVersionUpdate(op.version);
-		} else if (compareSummaryFormatVersions(resolvedVersion, this.writeFormat) === 1) {
+		} else if (compareSummaryFormatVersions(version, this.writeFormat) === 1) {
 			// An op version newer than our current version should not be received. If this happens, either an
 			// incorrect op version has been written or an update op was skipped.
 			const error = 'Newer op version received by a client that has yet to be updated.';
@@ -1115,7 +1265,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 		this.interner = new MutableStringInterner([initialTree.definition]);
 		const oldIdCompressor = this.idCompressor;
 		// Create the IdCompressor that will be used after the upgrade
-		const newIdCompressor = new IdCompressor(createSessionId(), reservedIdCount); // TODO: attribution info
+		const newIdCompressor = new IdCompressor(createSessionId(), reservedIdCount, this.attributionId, this.logger);
 		const newContext = getNodeIdContext(newIdCompressor);
 		// Generate all local IDs in the new compressor that were in the old compressor and preserve their UUIDs.
 		// This will allow the client to continue to use local IDs that were allocated pre-upgrade
@@ -1130,7 +1280,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 			}
 		};
 		// Construct a temporary "ghost" compressor which is used to generate final IDs that will be consistent across all upgrading clients
-		const ghostIdCompressor = new IdCompressor(ghostSessionId, reservedIdCount); // TODO: attribution info
+		const ghostIdCompressor = new IdCompressor(ghostSessionId, reservedIdCount);
 		const ghostContext = getNodeIdContext(ghostIdCompressor);
 		if (this.summarizeHistory) {
 			// All clients have the full history, and can therefore all "generate" the same final IDs for every ID in the history

package/src/SharedTreeEncoder.ts

@@ -134,18 +134,9 @@ export class SharedTreeEncoder_0_1_1 {
 		interner: StringInterner,
 		serializedIdCompressor: SerializedIdCompressorWithNoSession
 	): SharedTreeSummary {
-		if (this.summarizeHistory) {
-			return this.fullHistorySummarizer(edits, currentView, idNormalizer, interner, serializedIdCompressor);
-		} else {
-			return this.noHistorySummarizer(
-				edits,
-				currentView,
-				idContext,
-				idNormalizer,
-				interner,
-				serializedIdCompressor
-			);
-		}
+		return this.summarizeHistory
+			? this.fullHistorySummarizer(edits, currentView, idNormalizer, interner, serializedIdCompressor)
+			: this.noHistorySummarizer(edits, currentView, idContext, idNormalizer, interner, serializedIdCompressor);
 	}
 
 	/**
@@ -159,7 +150,7 @@ export class SharedTreeEncoder_0_1_1 {
 			idCompressor: serializedIdCompressor,
 			version,
 		}: SharedTreeSummary,
-		attributionId?: AttributionId
+		attributionId: AttributionId
 	): SummaryContents {
 		assert(version === WriteFormat.v0_1_1, `Invalid summary version to decode: ${version}, expected: 0.1.1`);
 		assert(typeof editHistory === 'object', '0.1.1 summary encountered with non-object edit history.');
@@ -364,11 +355,9 @@ export class SharedTreeEncoder_0_0_2 {
 		currentView: RevisionView,
 		idConverter: NodeIdConverter
 	): SharedTreeSummary_0_0_2 {
-		if (this.summarizeHistory) {
-			return this.fullHistorySummarizer(edits, currentView, idConverter);
-		} else {
-			return this.noHistorySummarizer(edits, currentView, idConverter);
-		}
+		return this.summarizeHistory
+			? this.fullHistorySummarizer(edits, currentView, idConverter)
+			: this.noHistorySummarizer(edits, currentView, idConverter);
 	}
 
 	/**

package/src/TransactionInternal.ts

@@ -347,19 +347,17 @@ export class GenericTransaction {
 		}
 		const resolvedChange = resolutionResult.result;
 		const changeResult = this.policy.dispatchChange(this.state, resolvedChange);
-		if (Result.isOk(changeResult)) {
-			this.state = {
-				status: EditStatus.Applied,
-				view: changeResult.result,
-				changes: this.changes.concat(change),
-				steps: this.steps.concat({ resolvedChange, after: changeResult.result }),
-			};
-		} else {
-			this.state = {
-				...this.state,
-				...changeResult.error,
-			};
-		}
+		this.state = Result.isOk(changeResult)
+			? {
+					status: EditStatus.Applied,
+					view: changeResult.result,
+					changes: this.changes.concat(change),
+					steps: this.steps.concat({ resolvedChange, after: changeResult.result }),
+			  }
+			: {
+					...this.state,
+					...changeResult.error,
+			  };
 		return this;
 	}
 }

package/src/id-compressor/IdCompressor.ts

@@ -5,6 +5,7 @@
 
 /* eslint-disable @typescript-eslint/restrict-plus-operands */
 
+import { ITelemetryLogger } from '@fluidframework/common-definitions';
 import BTree from 'sorted-btree';
 import {
 	assert,
@@ -384,7 +385,8 @@ export class IdCompressor {
 	public constructor(
 		public readonly localSessionId: SessionId,
 		public readonly reservedIdCount: number,
-		attributionId?: AttributionId
+		attributionId?: AttributionId,
+		private readonly logger?: ITelemetryLogger
 	) {
 		assert(reservedIdCount >= 0, 'reservedIdCount must be non-negative');
 		if (attributionId !== undefined) {
@@ -565,6 +567,7 @@ export class IdCompressor {
 		const finalizeCount = normalizedLastFinalizedLocal - newLastFinalizedLocal;
 		assert(finalizeCount >= 1, 'Cannot finalize an empty range.');
 
+		let eagerFinalIdCount = 0;
 		let initialClusterCount = 0;
 		let remainingCount = finalizeCount;
 		let newBaseUuid: NumericUuid | undefined;
@@ -577,6 +580,7 @@ export class IdCompressor {
 					Math.min(currentCluster.count + finalizeCount, currentCluster.capacity) -
 					1) as FinalCompressedId;
 				if (lastFinalInCluster > lastKnownFinal) {
+					eagerFinalIdCount = lastFinalInCluster - (lastKnownFinal + 1);
 					this.sessionIdNormalizer.addFinalIds(
 						(lastKnownFinal + 1) as FinalCompressedId,
 						lastFinalInCluster,
@@ -596,6 +600,7 @@ export class IdCompressor {
 					// The cluster is full but is the last in the list of clusters.
 					// This allows it to be expanded instead of allocating a new one.
 					const expansionAmount = this.newClusterCapacity + overflow;
+					const previousCapacity = currentCluster.capacity;
 					currentCluster.capacity += expansionAmount;
 					this.nextClusterBaseFinalId = (this.nextClusterBaseFinalId + expansionAmount) as FinalCompressedId;
 					assert(
@@ -617,6 +622,13 @@ export class IdCompressor {
 						const lastFinalizedFinal = (currentBaseFinalId + currentCluster.count - 1) as FinalCompressedId;
 						const finalPivot = (lastFinalizedFinal - overflow + 1) as FinalCompressedId;
 						this.sessionIdNormalizer.addFinalIds(finalPivot, lastFinalizedFinal, currentCluster);
+						this.logger?.sendTelemetryEvent({
+							eventName: 'IdCompressor:ClusterExpansion',
+							sessionId: this.localSessionId,
+							previousCapacity,
+							newCapacity: currentCluster.capacity,
+							overflow,
+						});
 					}
 				}
 			} else {
@@ -625,10 +637,18 @@ export class IdCompressor {
 				newBaseUuid = incrementUuid(currentCluster.baseUuid, currentCluster.capacity);
 				currentCluster.count += remainingCapacity;
 				remainingCount -= remainingCapacity;
+				this.logger?.sendTelemetryEvent({
+					eventName: 'IdCompressor:OverfilledCluster',
+					sessionId: this.localSessionId,
+				});
 			}
 		} else {
 			// Session has never made a cluster, form a new one with the session UUID as the baseUuid
 			newBaseUuid = session.sessionUuid;
+			this.logger?.sendTelemetryEvent({
+				eventName: 'IdCompressor:FirstCluster',
+				sessionId: this.localSessionId,
+			});
 		}
 
 		// Finalizing a range results in one of three cases:
@@ -652,9 +672,10 @@ export class IdCompressor {
 			}
 
 			newBaseFinalId = this.nextClusterBaseFinalId;
+			const newCapacity = Math.max(this.newClusterCapacity, remainingCount);
 			newCluster = {
 				baseUuid: newBaseUuid,
-				capacity: Math.max(this.newClusterCapacity, remainingCount),
+				capacity: newCapacity,
 				count: remainingCount,
 				session,
 			};
@@ -663,6 +684,12 @@ export class IdCompressor {
 			localIdPivot = (newFirstFinalizedLocal - usedCapacity) as LocalCompressedId;
 
 			if (isLocal) {
+				this.logger?.sendTelemetryEvent({
+					eventName: 'IdCompressor:NewCluster',
+					sessionId: this.localSessionId,
+					clusterCapacity: newCapacity,
+					clusterCount: remainingCount,
+				});
 				const lastFinalizedFinal = (newBaseFinalId + newCluster.count - 1) as FinalCompressedId;
 				this.sessionIdNormalizer.addFinalIds(newBaseFinalId, lastFinalizedFinal, newCluster);
 			}
@@ -779,6 +806,16 @@ export class IdCompressor {
 			}
 		}
 
+		if (isLocal) {
+			this.logger?.sendTelemetryEvent({
+				eventName: 'IdCompressor:IdCompressorStatus',
+				eagerFinalIdCount,
+				localIdCount: remainingCount,
+				overridesCount: overrides?.length ?? 0,
+				sessionId: this.localSessionId,
+			});
+		}
+
 		session.lastFinalizedLocalId = newLastFinalizedLocal;
 	}
 
@@ -1014,11 +1051,9 @@ export class IdCompressor {
 			// `localOverrides`s. Otherwise, it is a sequential allocation from the session UUID and can simply be negated and
 			// added to that UUID to obtain the stable ID associated with it.
 			const localOverride = this.localOverrides?.get(id);
-			if (localOverride !== undefined) {
-				return localOverride;
-			} else {
-				return stableIdFromNumericUuid(this.localSession.sessionUuid, idOffset - 1);
-			}
+			return localOverride !== undefined
+				? localOverride
+				: stableIdFromNumericUuid(this.localSession.sessionUuid, idOffset - 1);
 		}
 	}
 
@@ -1056,14 +1091,10 @@ export class IdCompressor {
 			const [key, compressionMapping] = closestMatch;
 			if (!IdCompressor.isClusterInfo(compressionMapping)) {
 				if (key === inversionKey) {
-					if (IdCompressor.isUnfinalizedOverride(compressionMapping)) {
-						return compressionMapping;
-					} else {
-						return (
-							compressionMapping.associatedLocalId ??
-							(compressionMapping.originalOverridingFinal as SessionSpaceCompressedId)
-						);
-					}
+					return IdCompressor.isUnfinalizedOverride(compressionMapping)
+						? compressionMapping
+						: compressionMapping.associatedLocalId ??
+								(compressionMapping.originalOverridingFinal as SessionSpaceCompressedId);
 				}
 			} else {
 				if (!isStable) {

package/src/index.ts

@@ -91,6 +91,10 @@ export {
 	TraitLocationInternal,
 } from './persisted-types';
 export {
+	SharedTreeArgs,
+	SharedTreeOptions,
+	SharedTreeOptions_0_0_2,
+	SharedTreeOptions_0_1_1,
 	SharedTreeFactory,
 	SharedTree,
 	EditCommittedHandler,