@fluidframework/id-compressor 3.3.0 → 3.5.0

package/src/idCompressor.ts

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { bufferToString, stringToBuffer } from "@fluid-internal/client-utils";
-import type { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
+import { bufferToString, createEmitter, stringToBuffer } from "@fluid-internal/client-utils";
+import type { ITelemetryBaseLogger, Listenable } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import type { TelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 import {
@@ -54,6 +54,9 @@ import type {
 	SessionSpaceCompressedId,
 	StableId,
 	ShardSynchronizationToken,
+	SerializedIdCompressorShard,
+	ParentShardSynchronizationToken,
+	IdCompressorEvents,
 } from "./types/index.js";
 import { SerializationVersion } from "./types/index.js";
 import {
@@ -75,10 +78,26 @@ function rangeFinalizationError(expectedStart: number, actualStart: number): Log
 
 const MAX_STRIDE_LENGTH = 1000000;
 
+/**
+ * Validates the generation count in a shard synchronization token.
+ *
+ * @param localGenCount - The number of positions filled, including backfilled positions.
+ * @throws {@link TypeError} if the count is not a nonnegative safe integer.
+ */
+function validateShardGenerationCount(localGenCount: number): void {
+	if (!Number.isSafeInteger(localGenCount) || localGenCount < 0) {
+		throw new TypeError("Invalid shard synchronization token generation count.");
+	}
+}
+
 /**
  * See {@link IIdCompressor} and {@link IIdCompressorCore}
  */
 export class IdCompressor implements IIdCompressor, IIdCompressorCore {
+	private readonly eventEmitter = createEmitter<IdCompressorEvents>();
+
+	public readonly events: Listenable<IdCompressorEvents> = this.eventEmitter;
+
 	/**
 	 * Max allowed initial cluster size.
 	 */
@@ -261,9 +280,6 @@ export class IdCompressor implements IIdCompressor, IIdCompressorCore {
 		this.ongoingGhostSession = { ghostSessionId };
 	}
 
-	/**
-	 * {@inheritdoc IIdCompressorCore.beginGhostSession}
-	 */
 	public beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): void {
 		if (this.shardingState) {
 			throw new Error("Cannot start a ghost session while sharded.");
@@ -276,10 +292,7 @@ export class IdCompressor implements IIdCompressor, IIdCompressorCore {
 		}
 	}
 
-	/**
-	 * {@inheritdoc IIdCompressorCore.shard}
-	 */
-	public shard(newShardCount: number): SerializedIdCompressorWithOngoingSession[] {
+	public shard(newShardCount: number): SerializedIdCompressorShard[] {
 		if (!Number.isSafeInteger(newShardCount) || newShardCount <= 0) {
 			throw new Error("Shard count must be a positive safe integer");
 		}
@@ -316,7 +329,7 @@ export class IdCompressor implements IIdCompressor, IIdCompressorCore {
 		const serialized = this.serialize(true);
 		const { localGenCount: parentGenCount } = this;
 
-		const shards: SerializedIdCompressorWithOngoingSession[] = [];
+		const shards: SerializedIdCompressorShard[] = [];
 
 		// Children are positioned at consecutive positions within the parents current stride cycle
 		// e.g. if parent owns the "evens" space (-2, -4, -6, ...) and is sharded into 3 (two children)
@@ -346,14 +359,15 @@ export class IdCompressor implements IIdCompressor, IIdCompressorCore {
 				shardId: childShardId,
 			};
 
-			shards.push(child.serialize(true));
+			shards.push({
+				serialized: child.serialize(true),
+				syncToken: child.makeShardToken(false),
+			});
 		}
 
 		return shards;
 	}
-	/**
-	 * {@inheritdoc IIdCompressorCore.synchronizeWithShard}
-	 */
+
 	public synchronizeWithShard(syncToken: ShardSynchronizationToken): void {
 		const isNowLeaf = this.synchronizeChild(syncToken);
 		// A disposal token additionally reclaims the child's ID space. If reclaiming the last child
@@ -366,6 +380,54 @@ export class IdCompressor implements IIdCompressor, IIdCompressorCore {
 		}
 	}
 
+	public getChildShardSyncToken(
+		childToken: ShardSynchronizationToken,
+	): ParentShardSynchronizationToken {
+		if (!this.shardingState?.activeChildIds.has(childToken.shardId)) {
+			throw new Error("Cannot get a synchronization token for an inactive child shard.");
+		}
+		const token: ParentShardSynchronizationToken = {
+			type: "parentIdSpaceShardSyncToken",
+			shardId: childToken.shardId,
+			localGenCount: this.localGenCount,
+		};
+		return token;
+	}
+
+	public synchronizeWithParent(token: ParentShardSynchronizationToken): void {
+		const state = this.shardingState;
+		if (
+			token.type !== "parentIdSpaceShardSyncToken" ||
+			state?.shardId === undefined ||
+			state.shardId !== token.shardId
+		) {
+			throw new Error("Invalid parent synchronization token for this child shard.");
+		}
+		validateShardGenerationCount(token.localGenCount);
+		if (token.localGenCount <= this.localGenCount) {
+			// A child can already be ahead through its own allocations. Its local range
+			// then includes the parent's IDs through this generation count.
+			return;
+		}
+		this.backfillToNextStridePosition(token.localGenCount, state.currentStride);
+	}
+
+	/**
+	 * Adds IDs through the next position in this shard's stride after the given generation count.
+	 */
+	private backfillToNextStridePosition(targetGenCount: number, stride: number): void {
+		if (targetGenCount <= this.localGenCount) {
+			return;
+		}
+		const count = Math.ceil((targetGenCount - this.localGenCount + 1) / stride) * stride;
+		const nextGenCount = this.localGenCount + count;
+		if (!Number.isSafeInteger(nextGenCount)) {
+			throw new TypeError("Shard progress exceeds the supported ID space.");
+		}
+		this.normalizer.addLocalRange(this.localGenCount + 1, count);
+		this.localGenCount = nextGenCount;
+	}
+
 	private synchronizeChild(syncToken: ShardToken): boolean {
 		const childDisposed = syncToken.disposed;
 		if (this.writeVersion < SerializationVersion.V3) {
@@ -386,39 +448,27 @@ export class IdCompressor implements IIdCompressor, IIdCompressorCore {
 				`Cannot synchronize with child with ID ${childShardId}: not in active children set`,
 			);
 		}
+		validateShardGenerationCount(syncToken.localGenCount);
+
+		// A last-child disposal realigns on the original stride. Backfill before changing
+		// membership so invalid progress cannot accidentally reclaim the child.
+		const isLeaf = childDisposed && activeChildIds.size === 1;
+		this.backfillToNextStridePosition(
+			syncToken.localGenCount,
+			isLeaf ? originalStride : this.shardingState.currentStride,
+		);
 
-		// Only disposal removes the child from the active set. A plain synchronization leaves the
-		// child active so it can continue generating IDs and be synchronized with again later.
+		// A plain synchronization leaves the child active so it can keep generating IDs.
 		if (childDisposed) {
 			activeChildIds.delete(childShardId);
-		}
-
-		const isLeaf = activeChildIds.size === 0;
-		if (isLeaf && childDisposed) {
-			this.shardingState.currentStride = originalStride;
-		}
-
-		// Read currentStride after the possible stride reset above, so that a leaf-making disposal
-		// realigns the parent on its original (reclaimed) stride rather than the wider sharded stride.
-		const { currentStride } = this.shardingState;
-		const childGenCount = syncToken.localGenCount;
-
-		// Realign parent to next position in its sequence if child is ahead
-		if (childGenCount > this.localGenCount) {
-			// Find next aligned position in parent's sequence after child's genCount
-			const distance = childGenCount - this.localGenCount + 1;
-			const steps = Math.ceil(distance / currentStride);
-			const count = steps * currentStride;
-			this.normalizer.addLocalRange(this.localGenCount + 1, count);
-			this.localGenCount += count;
+			if (isLeaf) {
+				this.shardingState.currentStride = originalStride;
+			}
 		}
 
 		return isLeaf;
 	}
 
-	/**
-	 * {@inheritdoc IIdCompressorCore.dispose}
-	 */
 	public disposeShard(): ShardSynchronizationToken | undefined {
 		if (this.shardingState === undefined) {
 			return undefined;
@@ -438,9 +488,6 @@ export class IdCompressor implements IIdCompressor, IIdCompressorCore {
 		return token;
 	}
 
-	/**
-	 * {@inheritdoc IIdCompressorCore.getShardSyncToken}
-	 */
 	public getShardSyncToken(): ShardSynchronizationToken | undefined {
 		if (this.shardingState === undefined) {
 			return undefined;
@@ -639,6 +686,7 @@ export class IdCompressor implements IIdCompressor, IIdCompressorCore {
 		}
 
 		assert(!session.isEmpty(), 0x757 /* Empty sessions should not be created. */);
+		this.eventEmitter.emit("rangeFinalized", range);
 	}
 
 	private addEmptyCluster(session: Session, capacity: number): IdCluster {

package/src/index.ts

@@ -22,16 +22,19 @@ export {
 	isStableId,
 } from "./utilities.js";
 export type {
-	IIdCompressorCore,
+	IdCreationRange,
 	IIdCompressor,
+	IIdCompressorCore,
+	IdCompressorEvents,
+	OpSpaceCompressedId,
+	ParentShardSynchronizationToken,
 	SerializedIdCompressor,
-	SerializedIdCompressorWithOngoingSession,
 	SerializedIdCompressorWithNoSession,
-	SessionSpaceCompressedId,
-	OpSpaceCompressedId,
+	SerializedIdCompressorWithOngoingSession,
+	SerializedIdCompressorShard,
 	SessionId,
-	StableId,
-	IdCreationRange,
-	ShardToken,
+	SessionSpaceCompressedId,
 	ShardSynchronizationToken,
+	ShardToken,
+	StableId,
 } from "./types/index.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/id-compressor";
-export const pkgVersion = "3.3.0";
+export const pkgVersion = "3.5.0";

package/src/test/types/validateIdCompressorPrevious.generated.ts

@@ -7,7 +7,7 @@
  * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
  * Generated by "flub generate typetests" from @fluid-tools/build-cli.
  *
- * Baseline (previous) version: 3.2.0
+ * Baseline (previous) version: 3.4.0
  */
 
 import type { TypeOnly, MinimalType, FullType, requireAssignableTo } from "@fluidframework/build-tools";
@@ -17,66 +17,6 @@ import type * as current from "@fluidframework/id-compressor/legacy";
 
 declare type MakeUnusedImportErrorsGoAway<T> = TypeOnly<T> | MinimalType<T> | FullType<T> | typeof old | typeof current | requireAssignableTo<true, true>;
 
-/*
- * Validate backward compatibility by using the current type in place of the old type.
- * If this test starts failing, it indicates a change that is not backward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "Function_createIdCompressor": {"backCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type current_as_old_for_Function_createIdCompressor = requireAssignableTo<TypeOnly<typeof current.createIdCompressor>, TypeOnly<typeof old.createIdCompressor>>
-
-/*
- * Validate backward compatibility by using the current type in place of the old type.
- * If this test starts failing, it indicates a change that is not backward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "Function_createSessionId": {"backCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type current_as_old_for_Function_createSessionId = requireAssignableTo<TypeOnly<typeof current.createSessionId>, TypeOnly<typeof old.createSessionId>>
-
-/*
- * Validate backward compatibility by using the current type in place of the old type.
- * If this test starts failing, it indicates a change that is not backward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "Function_deserializeIdCompressor": {"backCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type current_as_old_for_Function_deserializeIdCompressor = requireAssignableTo<TypeOnly<typeof current.deserializeIdCompressor>, TypeOnly<typeof old.deserializeIdCompressor>>
-
-/*
- * Validate backward compatibility by using the current type in place of the old type.
- * If this test starts failing, it indicates a change that is not backward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "Function_serializeIdCompressor": {"backCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type current_as_old_for_Function_serializeIdCompressor = requireAssignableTo<TypeOnly<typeof current.serializeIdCompressor>, TypeOnly<typeof old.serializeIdCompressor>>
-
-/*
- * Validate forward compatibility by using the old type in place of the current type.
- * If this test starts failing, it indicates a change that is not forward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "Interface_IdCreationRange": {"forwardCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type old_as_current_for_Interface_IdCreationRange = requireAssignableTo<TypeOnly<old.IdCreationRange>, TypeOnly<current.IdCreationRange>>
-
-/*
- * Validate backward compatibility by using the current type in place of the old type.
- * If this test starts failing, it indicates a change that is not backward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "Interface_IdCreationRange": {"backCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type current_as_old_for_Interface_IdCreationRange = requireAssignableTo<TypeOnly<current.IdCreationRange>, TypeOnly<old.IdCreationRange>>
-
 /*
  * Validate backward compatibility by using the current type in place of the old type.
  * If this test starts failing, it indicates a change that is not backward compatible.
@@ -104,66 +44,6 @@ declare type old_as_current_for_TypeAlias_OpSpaceCompressedId = requireAssignabl
  */
 declare type current_as_old_for_TypeAlias_OpSpaceCompressedId = requireAssignableTo<TypeOnly<current.OpSpaceCompressedId>, TypeOnly<old.OpSpaceCompressedId>>
 
-/*
- * Validate forward compatibility by using the old type in place of the current type.
- * If this test starts failing, it indicates a change that is not forward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "TypeAlias_SerializedIdCompressor": {"forwardCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type old_as_current_for_TypeAlias_SerializedIdCompressor = requireAssignableTo<TypeOnly<old.SerializedIdCompressor>, TypeOnly<current.SerializedIdCompressor>>
-
-/*
- * Validate backward compatibility by using the current type in place of the old type.
- * If this test starts failing, it indicates a change that is not backward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "TypeAlias_SerializedIdCompressor": {"backCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type current_as_old_for_TypeAlias_SerializedIdCompressor = requireAssignableTo<TypeOnly<current.SerializedIdCompressor>, TypeOnly<old.SerializedIdCompressor>>
-
-/*
- * Validate forward compatibility by using the old type in place of the current type.
- * If this test starts failing, it indicates a change that is not forward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "TypeAlias_SerializedIdCompressorWithNoSession": {"forwardCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type old_as_current_for_TypeAlias_SerializedIdCompressorWithNoSession = requireAssignableTo<TypeOnly<old.SerializedIdCompressorWithNoSession>, TypeOnly<current.SerializedIdCompressorWithNoSession>>
-
-/*
- * Validate backward compatibility by using the current type in place of the old type.
- * If this test starts failing, it indicates a change that is not backward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "TypeAlias_SerializedIdCompressorWithNoSession": {"backCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type current_as_old_for_TypeAlias_SerializedIdCompressorWithNoSession = requireAssignableTo<TypeOnly<current.SerializedIdCompressorWithNoSession>, TypeOnly<old.SerializedIdCompressorWithNoSession>>
-
-/*
- * Validate forward compatibility by using the old type in place of the current type.
- * If this test starts failing, it indicates a change that is not forward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "TypeAlias_SerializedIdCompressorWithOngoingSession": {"forwardCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type old_as_current_for_TypeAlias_SerializedIdCompressorWithOngoingSession = requireAssignableTo<TypeOnly<old.SerializedIdCompressorWithOngoingSession>, TypeOnly<current.SerializedIdCompressorWithOngoingSession>>
-
-/*
- * Validate backward compatibility by using the current type in place of the old type.
- * If this test starts failing, it indicates a change that is not backward compatible.
- * To acknowledge the breaking change, add the following to package.json under
- * typeValidation.broken:
- * "TypeAlias_SerializedIdCompressorWithOngoingSession": {"backCompat": false}
- */
-// @ts-expect-error compatibility expected to be broken
-declare type current_as_old_for_TypeAlias_SerializedIdCompressorWithOngoingSession = requireAssignableTo<TypeOnly<current.SerializedIdCompressorWithOngoingSession>, TypeOnly<old.SerializedIdCompressorWithOngoingSession>>
-
 /*
  * Validate forward compatibility by using the old type in place of the current type.
  * If this test starts failing, it indicates a change that is not forward compatible.

package/src/types/idCompressor.ts

@@ -9,6 +9,7 @@ import type {
 	SessionSpaceCompressedId,
 	StableId,
 } from "./identifiers.js";
+import type { Listenable } from "@fluidframework/core-interfaces";
 import type {
 	IdCreationRange,
 	SerializedIdCompressorWithNoSession,
@@ -101,6 +102,11 @@ export type SerializationVersion =
  * @internal
  */
 export interface IIdCompressorCore {
+	/**
+	 * Events emitted by the ID compressor.
+	 */
+	readonly events: Listenable<IdCompressorEvents>;
+
 	/**
 	 * Returns a range of IDs created by this session in a format for sending to the server for finalizing.
 	 * The range will include all IDs generated via calls to `generateCompressedId` since the last time a
@@ -174,12 +180,11 @@ export interface IIdCompressorCore {
 	 * @param newShardCount - The number of additional different shards to split this compressor into.
 	 * Must be a positive safe integer.
 	 * @throws If `newShardCount` is not a positive safe integer or the resulting stride exceeds the sharding limit.
-	 * @returns An array of serialized compressors of size `newShardCount`.
-	 * These can be passed across a marshalling boundary and rehydrated on the other side, and will safely share the ID space of `this`.
+	 * @returns An array of `newShardCount` {@link SerializedIdCompressorShard} objects.
 	 * Note that this method should only be needed when multiple JS runtimes are in play, as sharded compressors essentially
 	 * attempt to emulate a single static compressor and any code running in the same JS runtime can simply use statics.
 	 */
-	shard(newShardCount: number): SerializedIdCompressorWithOngoingSession[];
+	shard(newShardCount: number): SerializedIdCompressorShard[];
 
 	/**
 	 * Synchronizes `this` compressor with a child shard. Synchronization will occur for the state of the child at the time `syncToken`
@@ -192,9 +197,37 @@ export interface IIdCompressorCore {
 	 * be disposed from the leaves upwards.
 	 * @param syncToken - The token for the shard, obtained by calling {@link IIdCompressorCore.getShardSyncToken} (non-destructive
 	 * synchronization) or {@link IIdCompressorCore.disposeShard} (synchronization plus reclamation of the disposed shard's ID space).
+	 * @throws `TypeError` if the token's generation count is not a nonnegative safe integer.
 	 */
 	synchronizeWithShard(syncToken: ShardSynchronizationToken): void;
 
+	/**
+	 * Gets a synchronization token from this compressor for an active child shard.
+	 *
+	 * @remarks
+	 * The child can apply this token without replacing its compressor.
+	 *
+	 * @param childToken - A token from the child shard that will receive this token.
+	 * @returns This parent's synchronization token for that child.
+	 * @throws If the child shard is not active on this compressor.
+	 */
+	getChildShardSyncToken(
+		childToken: ShardSynchronizationToken,
+	): ParentShardSynchronizationToken;
+
+	/**
+	 * Synchronizes this child shard with its parent's token.
+	 *
+	 * @remarks
+	 * This method keeps the child's allocation stride and does not finalize ID creation ranges.
+	 * Apply creation ranges from {@link IIdCompressorCore.events} separately, in order.
+	 *
+	 * @param token - Synchronization token obtained from this child's parent.
+	 * @throws If the token names another child or contains invalid state.
+	 * @throws `TypeError` if the token's generation count is not a nonnegative safe integer.
+	 */
+	synchronizeWithParent(token: ParentShardSynchronizationToken): void;
+
 	/**
 	 * Returns undefined if this compressor is not part of a shard group, and otherwise returns a synchronization token for this shard
 	 * that can be used when calling {@link IIdCompressorCore.synchronizeWithShard}. This does NOT dispose the shard.
@@ -234,24 +267,47 @@ export interface IIdCompressorCore {
 }
 
 /**
- * The state shared by all shard tokens: enough information to identify a shard and its progress
- * through its stride pattern. This is used to track which shard generated which IDs and to manage
- * reclamation of a disposed shard's ID space. The {@link ShardToken.disposed} flag distinguishes a
- * plain synchronization token from a disposal token. The branded {@link ShardSynchronizationToken}
- * is the concrete type handed to consumers.
+ * The serialized state of a new child compressor and its initial synchronization token.
+ *
+ * @sealed
+ * @internal
+ */
+export interface SerializedIdCompressorShard {
+	/**
+	 * Serialized child state that can be rehydrated across a marshalling boundary.
+	 */
+	readonly serialized: SerializedIdCompressorWithOngoingSession;
+
+	/**
+	 * Initial, non-disposing token for this child shard.
+	 *
+	 * @remarks
+	 * After the child generates IDs, obtain its updated token before synchronizing
+	 * with the parent or reclaiming the child's ID space.
+	 *
+	 * This can be used to immediately dispose of a new shard if it is not used.
+	 */
+	readonly syncToken: ShardSynchronizationToken;
+}
+
+/**
+ * State shared by shard synchronization tokens.
+ * @remarks
+ * Treat these tokens as opaque: the compressor owns their interpretation and may add state in the future.
+ * The {@link ShardToken.disposed} flag distinguishes ordinary synchronization from shard reclamation.
+ * The branded {@link ShardSynchronizationToken} is the concrete child-to-parent token.
  * @internal
  */
 export interface ShardToken {
 	/**
-	 * The number of positions filled in this shard's stride pattern.
-	 * This tracks progress through the stride cycle, not the count of IDs actually generated.
-	 * For example, when a shard is created, it backfills entries for positions in its stride,
-	 * so this value may be non-zero even if the shard hasn't generated any IDs yet.
+	 * The sending compressor's generation count, which can include backfilled positions
+	 * rather than only IDs it generated.
+	 * @remarks Must be a nonnegative safe integer.
 	 */
 	localGenCount: number;
 
 	/**
-	 * Unique identifier for this shard within its parent.
+	 * Identifies the child shard involved in synchronization with its parent.
 	 */
 	shardId: SessionId;
 
@@ -272,27 +328,50 @@ export type ShardSynchronizationToken = ShardToken & {
 	readonly ShardSynchronizationToken: "c79724e1-9103-4415-95b5-bebb932be404";
 };
 
+/**
+ * A synchronization token from a parent to one of its active child shards.
+ * @remarks
+ * Unlike the child-to-parent {@link ShardSynchronizationToken}, this token cannot dispose a shard.
+ * It does not finalize ID creation ranges.
+ * @internal
+ */
+export interface ParentShardSynchronizationToken
+	extends Readonly<Omit<ShardToken, "disposed">> {
+	/** Identifies the parent-to-child token across a message boundary. */
+	readonly type: "parentIdSpaceShardSyncToken";
+}
+
+/**
+ * Events for finalized ID creation ranges.
+ * @internal
+ */
+export interface IdCompressorEvents {
+	/** Reports a range after finalization succeeds. */
+	rangeFinalized: (range: IdCreationRange) => void;
+}
 /**
  * A distributed UUID generator and compressor.
+ *
+ * @remarks
  * `IdCompressor` offers the ability to generate arbitrary non-colliding v4 UUIDs, called stable IDs, while compressing them into small integers
  * for efficient storage and transmission. It also provides the ability to decompress these integers back into their original UUIDs.
  *
  * The compressor is designed to be used in a distributed environment, where multiple clients may be generating IDs concurrently.
- * IDs generated by a compressor, via calls to `generateCompressedId`, are created in the compressor's "local" session.
+ * IDs generated by a compressor, via calls to {@link IIdCompressor.generateCompressedId}, are created in the compressor's "local" session.
  * These IDs are unique within the session, but may not be unique across sessions. In the context of Fluid, the scope of a session
  * is the same as the scope of a container. This means that anytime IDs are transferred between sessions, they must be translated
  * through a process called "normalization":
+ *
  * - The scope of a local session (in which local IDs are unique) is called the "session space" of the client.
  * - The context of persisted state (in Fluid, this is the context of ops and summaries) is called "op space".
- * - `SessionSpaceCompressedId`s, generated via calls to `generateCompressedId`, should NEVER be serialized directly.
+ * - {@link SessionSpaceCompressedId | SessionSpaceCompressedIds}, generated via calls to {@link IIdCompressor.generateCompressedId}, should NEVER be serialized directly.
  * In Fluid, this means they should not be included in ops or summaries.
  * - Before serialization, IDs must be normalized to op space to ensure they are interpretable by other clients.
  * - Upon receipt, IDs should be normalized back to session space before use.
  *
- * Example Usage:
- *
- * ### Client A (Sender)
+ * @example
  *
+ * Client A (Sender)
  * ```typescript
  * // Generate several local IDs
  * const localId1 = idCompressor.generateCompressedId();
@@ -312,7 +391,7 @@ export type ShardSynchronizationToken = ShardToken & {
  * };
  * ```
  *
- * ### Client B (Receiver)
+ * Client B (Receiver)
  *
  * ```typescript
  * // Receive the message from Client A
@@ -334,27 +413,34 @@ export interface IIdCompressor {
 
 	/**
 	 * Generates a new compressed ID.
-	 * The returned ID is in session space and should not be serialized directly. See `IIdCompressor` for more details.
+	 *
+	 * @remarks The returned ID is in session space and should not be serialized directly.
+	 * @see {@link IIdCompressor} for more details.
 	 * @returns A new local ID in session space.
 	 */
 	generateCompressedId(): SessionSpaceCompressedId;
 
 	/**
 	 * Generates a new ID that is guaranteed to be unique across all sessions known to this compressor without the need for any
-	 * normalization. The returned ID is not guaranteed to be a compressed ID (small number); it may be a stable ID (UUID string).
+	 * normalization.
+	 *
+	 * @remarks The returned ID is not guaranteed to be a compressed ID (small number); it may be a stable ID (UUID string).
 	 * In Fluid, the likelihood of generating the bulkier stable ID is dictated by network conditions and is highly probable in
 	 * scenarios such as offline. This is still useful for use cases where simplicity is more important than performance and
 	 * this approach will often be superior to generating a UUID.
-	 * If small numbers are a requirement, `generateCompressedId` and normalization should be used instead.
-	 * See `IIdCompressor` for more details.
+	 *
+	 * If small numbers are a requirement, {@link IIdCompressor.generateCompressedId} and normalization should be used instead.
+	 * @see {@link IIdCompressor} for more details.
 	 * @returns A new local ID in session space.
 	 */
 	generateDocumentUniqueId(): (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId;
 
 	/**
 	 * Normalizes a session space ID into op space.
-	 * The returned ID is in op space and can be safely serialized.
+	 *
+	 * @remarks The returned ID is in op space and can be safely serialized.
 	 * However, it should be {@link IIdCompressor.normalizeToSessionSpace|normalized back to session space} before use.
+	 *
 	 * @param id - The local ID to normalize.
 	 * @returns The ID in op space.
 	 */
@@ -362,23 +448,25 @@ export interface IIdCompressor {
 
 	/**
 	 * Normalizes an ID into session space.
-	 * @param id - The ID to normalize.
-	 * @param originSessionId - The {@link IIdCompressor.localSessionId} of the compressor which {@link IIdCompressor.normalizeToOpSpace|encoded} `id`.
-	 * This might not be the client that created `id` in the first place, but rather the client that serialized it.
-	 * This is an important distinction in the case of a reference, where a client might refer to an ID created by another client.
-	 * @returns The session-space ID in the local session corresponding to `id`.
+	 *
 	 * @remarks
 	 * For this to be valid, `originSessionId` must be the {@link IIdCompressor.localSessionId} of the compressor that normalized `id` to op space.
-	 * Additionally, this compressor must know about the relevant {@link IdCreationRange} from the encoding `IIdCompressor`.
+	 * Additionally, this compressor must know about the relevant {@link IdCreationRange} from the encoding {@link IIdCompressor}.
 	 * This can be accomplished using creating the compressor using {@link (deserializeIdCompressor:1)},
 	 * or relying on something (like the Fluid runtime) to synchronize the range information using internal mechanisms.
 	 *
-	 * The {@link IIdCompressor} provided by the Fluid Framework runtime will automatically track {@link IdCreationRange| Id Creation Ranges} (via its own ops) from other clients in the container.
+	 * The {@link IIdCompressor} provided by the Fluid Framework runtime will automatically track {@link IdCreationRange | Id Creation Ranges} (via its own ops) from other clients in the container.
 	 * It is up to the user of the {@link IIdCompressor} to ensure the relevant session information is available,
 	 * either by depending on the originating client's session ID for ops, or by explicitly storing it alongside the data containing the {@link OpSpaceCompressedId}.
 	 *
 	 * Note that attachment summaries, while they are ops, are also interpreted as summaries without the context of their originating session,
 	 * so they should explicitly include session IDs if required to decode them just like regular summaries and exported data.
+	 *
+	 * @param id - The ID to normalize.
+	 * @param originSessionId - The {@link IIdCompressor.localSessionId} of the compressor which {@link IIdCompressor.normalizeToOpSpace|encoded} `id`.
+	 * This might not be the client that created `id` in the first place, but rather the client that serialized it.
+	 * This is an important distinction in the case of a reference, where a client might refer to an ID created by another client.
+	 * @returns The session-space ID in the local session corresponding to `id`.
 	 */
 	normalizeToSessionSpace(
 		id: OpSpaceCompressedId,