@fluidframework/id-compressor 3.2.0 → 3.4.0

package/lib/idCompressor.js

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { bufferToString, stringToBuffer } from "@fluid-internal/client-utils";
+import { bufferToString, createEmitter, stringToBuffer } from "@fluid-internal/client-utils";
 import { assert } from "@fluidframework/core-utils/internal";
 import { LoggingError, createChildLogger, extractTelemetryLoggerExt, } from "@fluidframework/telemetry-utils/internal";
 import { FinalSpace } from "./finalSpace.js";
@@ -10,23 +10,34 @@ import { isFinalId, } from "./identifiers.js";
 import { readBoolean, readNumber, readNumericUuid, writeBoolean, writeNumber, writeNumericUuid, } from "./persistanceUtilities.js";
 import { SessionSpaceNormalizer } from "./sessionSpaceNormalizer.js";
 import { Session, Sessions, getAlignedFinal, getAlignedLocal, lastFinalizedFinal, lastFinalizedLocal, } from "./sessions.js";
+import { SerializationVersion } from "./types/index.js";
 import { createSessionId, genCountFromLocalId, localIdFromGenCount, numericUuidFromStableId, offsetNumericUuid, stableIdFromNumericUuid, subtractNumericUuids, } from "./utilities.js";
-/**
- * The version of IdCompressor that is currently persisted.
- * This should not be changed without careful consideration to compatibility.
- */
-const currentWrittenVersion = 2;
 function rangeFinalizationError(expectedStart, actualStart) {
     return new LoggingError("Ranges finalized out of order", {
         expectedStart,
         actualStart,
     });
 }
+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) {
+    if (!Number.isSafeInteger(localGenCount) || localGenCount < 0) {
+        throw new TypeError("Invalid shard synchronization token generation count.");
+    }
+}
 /**
  * See {@link IIdCompressor} and {@link IIdCompressorCore}
  */
 export class IdCompressor {
     logger;
+    writeVersion;
+    eventEmitter = createEmitter();
+    events = this.eventEmitter;
     /**
      * Max allowed initial cluster size.
      */
@@ -37,11 +48,19 @@ export class IdCompressor {
     normalizer = new SessionSpaceNormalizer();
     // The number of IDs generated by the local session
     localGenCount = 0;
+    /**
+     * The sharding state of this compressor, if it has been sharded or is a shard itself.
+     * When defined, this compressor operates in "sharding mode" where:
+     * - IDs are generated using stride-based allocation (no eager finals)
+     * - The normalizer backfills all IDs in each stride cycle
+     * - Normal operation resumes when all children are disposed
+     */
+    shardingState;
     // #endregion
     // #region Final state
     /**
      * The gen count to be annotated on the range returned by the next call to `takeNextCreationRange`.
-     * This is advanced to `generatedIdCount` + 1 each time it is called.
+     * This is advanced to `localGenCount` + 1 each time it is called.
      * On the other hand, when `resetUnfinalizedCreationRange` is called,
      * this is moved back to the start of the unfinalized range, to ensure those IDs are included in the next range.
      */
@@ -65,8 +84,15 @@ export class IdCompressor {
     // The ongoing ghost session, if one exists.
     ongoingGhostSession;
     // #endregion
-    constructor(localSessionIdOrDeserialized, logger) {
+    constructor(localSessionIdOrDeserialized, logger, 
+    /**
+     * The version this compressor will write out.
+     * This applies to both `serialize` and creation range functions.
+     * This number also determines what features are available (e.g. sharding support starts at V3).
+     */
+    writeVersion) {
         this.logger = logger;
+        this.writeVersion = writeVersion;
         if (typeof localSessionIdOrDeserialized === "string") {
             this.localSessionId = localSessionIdOrDeserialized;
             this.localSession = this.sessions.getOrCreate(localSessionIdOrDeserialized);
@@ -94,29 +120,38 @@ export class IdCompressor {
             this.ongoingGhostSession.cluster.count++;
             return lastFinalizedFinal(this.ongoingGhostSession.cluster);
         }
-        else {
-            this.localGenCount++;
-            const lastCluster = this.localSession.getLastCluster();
-            if (lastCluster === undefined) {
-                this.telemetryLocalIdCount++;
-                return this.generateNextLocalId();
-            }
-            // If there exists a cluster of final IDs already claimed by the local session that still has room in it,
-            // it is known prior to range sequencing what a local ID's corresponding final ID will be.
-            // In this case, it is safe to return the final ID immediately. This is guaranteed to be safe because
-            // any op that the local session sends that contains one of those final IDs are guaranteed to arrive to
-            // collaborators *after* the one containing the creation range.
-            const clusterOffset = this.localGenCount - genCountFromLocalId(lastCluster.baseLocalId);
-            if (lastCluster.capacity > clusterOffset) {
-                this.telemetryEagerFinalIdCount++;
-                // Space in the cluster: eager final
-                return (lastCluster.baseFinalId +
-                    clusterOffset);
-            }
-            // No space in the cluster, return next local
+        // In sharding mode, always generate local IDs with stride-based allocation.
+        // Eager finals are disabled because shards backfill IDs not in their stride cycle.
+        // If another shard generated them as eager finals, ingesting IDs from another shard
+        // would fail depending on timing.
+        if (this.shardingState !== undefined) {
+            this.telemetryLocalIdCount++;
+            const { currentStride } = this.shardingState;
+            this.normalizer.addLocalRange(this.localGenCount + 1, currentStride);
+            this.localGenCount += currentStride;
+            return localIdFromGenCount(this.localGenCount);
+        }
+        // Normal ID generation
+        this.localGenCount++;
+        const lastCluster = this.localSession.getLastCluster();
+        if (lastCluster === undefined) {
             this.telemetryLocalIdCount++;
             return this.generateNextLocalId();
         }
+        // If there exists a cluster of final IDs already claimed by the local session that still has room in it,
+        // it is known prior to range sequencing what a local ID's corresponding final ID will be.
+        // In this case, it is safe to return the final ID immediately. This is guaranteed to be safe because
+        // any op that the local session sends that contains one of those final IDs are guaranteed to arrive to
+        // collaborators *after* the one containing the creation range.
+        const clusterOffset = this.localGenCount - genCountFromLocalId(lastCluster.baseLocalId);
+        if (lastCluster.capacity > clusterOffset) {
+            this.telemetryEagerFinalIdCount++;
+            // Space in the cluster: eager final
+            return (lastCluster.baseFinalId + clusterOffset);
+        }
+        // No space in the cluster, return next local
+        this.telemetryLocalIdCount++;
+        return this.generateNextLocalId();
     }
     generateDocumentUniqueId() {
         const id = this.generateCompressedId();
@@ -130,10 +165,10 @@ export class IdCompressor {
         assert(!this.ongoingGhostSession, 0x8fe /* Ghost session already in progress. */);
         this.ongoingGhostSession = { ghostSessionId };
     }
-    /**
-     * {@inheritdoc IIdCompressorCore.beginGhostSession}
-     */
     beginGhostSession(ghostSessionId, ghostSessionCallback) {
+        if (this.shardingState) {
+            throw new Error("Cannot start a ghost session while sharded.");
+        }
         this.startGhostSession(ghostSessionId);
         try {
             ghostSessionCallback();
@@ -142,12 +177,199 @@ export class IdCompressor {
             this.ongoingGhostSession = undefined;
         }
     }
+    shard(newShardCount) {
+        if (!Number.isSafeInteger(newShardCount) || newShardCount <= 0) {
+            throw new Error("Shard count must be a positive safe integer");
+        }
+        if (this.ongoingGhostSession) {
+            throw new Error("Cannot shard during ghost session");
+        }
+        if (this.writeVersion < SerializationVersion.V3) {
+            throw new Error(`Sharding requires document version ${SerializationVersion.V3} or higher, but this document is version ${this.writeVersion}`);
+        }
+        const currentStride = this.shardingState?.currentStride ?? 1;
+        const newStride = currentStride * (newShardCount + 1);
+        // ID usage is exponential in stride count. Limit to practical size to avoid overflow.
+        if (newStride > MAX_STRIDE_LENGTH) {
+            throw new Error("Sharding limit reached.");
+        }
+        assert(Number.isSafeInteger(newStride), 0xd52 /* Shard stride must be a safe integer */);
+        if (this.shardingState === undefined) {
+            // First time sharding - initialize state
+            this.shardingState = {
+                currentStride: newStride,
+                originalStride: 1,
+                activeChildIds: new Set(),
+            };
+        }
+        else {
+            this.shardingState.currentStride = newStride;
+        }
+        // Cache to avoid repeating per child
+        const serialized = this.serialize(true);
+        const { localGenCount: parentGenCount } = this;
+        const shards = [];
+        // 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)
+        // while at -8, then the child shards will start at -10 and -12 with a stride of 6
+        for (let i = 1; i <= newShardCount; i++) {
+            const childShardId = createSessionId();
+            this.shardingState.activeChildIds.add(childShardId);
+            const childLocalGenCount = parentGenCount + i * currentStride;
+            // This code results in a double roundtrip, but is probably plenty fast enough for scenarios that need sharding,
+            // as they necessarily have process boundaries to deal with.
+            // If this ever became an issue we can implement a fast clone of compressors
+            const child = deserializeIdCompressor(serialized, this.writeVersion);
+            const genCountJump = childLocalGenCount - parentGenCount;
+            assert(child.localGenCount === parentGenCount && genCountJump > 0, 0xd53 /* Child offsets incorrectly calculated. */);
+            child.normalizer.addLocalRange(child.localGenCount + 1, genCountJump);
+            child.localGenCount = childLocalGenCount;
+            child.shardingState = {
+                currentStride: newStride,
+                originalStride: newStride,
+                activeChildIds: new Set(),
+                shardId: childShardId,
+            };
+            shards.push({
+                serialized: child.serialize(true),
+                syncToken: child.makeShardToken(false),
+            });
+        }
+        return shards;
+    }
+    synchronizeWithShard(syncToken) {
+        const isNowLeaf = this.synchronizeChild(syncToken);
+        // A disposal token additionally reclaims the child's ID space. If reclaiming the last child
+        // returns this compressor to a leaf and it is the root (originalStride === 1), exit sharding mode.
+        if (syncToken.disposed) {
+            assert(this.shardingState !== undefined, 0xd54 /* Must be sharded */);
+            if (isNowLeaf && this.shardingState.originalStride === 1) {
+                this.shardingState = undefined;
+            }
+        }
+    }
+    getChildShardSyncToken(childToken) {
+        if (!this.shardingState?.activeChildIds.has(childToken.shardId)) {
+            throw new Error("Cannot get a synchronization token for an inactive child shard.");
+        }
+        const token = {
+            type: "parentIdSpaceShardSyncToken",
+            shardId: childToken.shardId,
+            localGenCount: this.localGenCount,
+        };
+        return token;
+    }
+    synchronizeWithParent(token) {
+        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.
+     */
+    backfillToNextStridePosition(targetGenCount, stride) {
+        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;
+    }
+    synchronizeChild(syncToken) {
+        const childDisposed = syncToken.disposed;
+        if (this.writeVersion < SerializationVersion.V3) {
+            throw new Error(`Sharding requires document version ${SerializationVersion.V3} or higher, but this document is version ${this.writeVersion}`);
+        }
+        if (this.shardingState === undefined) {
+            throw new Error("Must be in sharding mode.");
+        }
+        const childShardId = syncToken.shardId;
+        const { activeChildIds, originalStride } = this.shardingState;
+        // Verify this child belongs to us
+        if (!activeChildIds.has(childShardId)) {
+            throw new Error(`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);
+        // A plain synchronization leaves the child active so it can keep generating IDs.
+        if (childDisposed) {
+            activeChildIds.delete(childShardId);
+            if (isLeaf) {
+                this.shardingState.currentStride = originalStride;
+            }
+        }
+        return isLeaf;
+    }
+    disposeShard() {
+        if (this.shardingState === undefined) {
+            return undefined;
+        }
+        else {
+            if (this.shardingState.activeChildIds.size > 0) {
+                throw new Error("Cannot dispose a shard with active children.");
+            }
+        }
+        // A disposal token is a sync token that additionally signals reclamation of this shard's ID space.
+        const token = this.makeShardToken(true);
+        // Make this compressor unusable by replacing all methods with throwing stubs
+        // This is a one-time mutation that avoids runtime checks in every method
+        makeCompressorUnusable(this);
+        return token;
+    }
+    getShardSyncToken() {
+        if (this.shardingState === undefined) {
+            return undefined;
+        }
+        return this.makeShardToken(false);
+    }
+    /**
+     * Builds a token describing this shard's current progress.
+     * @param disposed - Whether the token also signals disposal (reclamation of this shard's ID space).
+     */
+    makeShardToken(disposed) {
+        assert(this.shardingState !== undefined, 0xd55 /* Compressor is not sharded. */);
+        // Root cannot produce a token (shardId is undefined for root)
+        if (this.shardingState.shardId === undefined) {
+            throw new Error("Cannot get a token for a root compressor - only shards can be disposed");
+        }
+        const token = {
+            localGenCount: this.localGenCount,
+            shardId: this.shardingState.shardId,
+            disposed,
+        };
+        return token;
+    }
     generateNextLocalId() {
         // Must tell the normalizer that we generated a local ID
         this.normalizer.addLocalRange(this.localGenCount, 1);
         return localIdFromGenCount(this.localGenCount);
     }
     takeNextCreationRange() {
+        // Child (non-root) shards must not submit their own creation ranges. All shards in a shard tree share a
+        // single session, and only the root shard is responsible for finalizing that session's IDs with the server.
+        // A child's generated IDs are reconciled with the root via shard synchronization tokens (see
+        // synchronizeWithShard / disposeShard), not by independently sending ranges, which would overlap and
+        // conflict with the root's ranges for the shared session.
+        if (this.shardingState?.shardId !== undefined) {
+            throw new Error("Cannot take a creation range from a non-root shard.");
+        }
         assert(!this.ongoingGhostSession, 0x8a6 /* IdCompressor should not be operated normally when in a ghost session */);
         const count = this.localGenCount - (this.nextRangeBaseGenCount - 1);
         if (count === 0) {
@@ -268,6 +490,7 @@ export class IdCompressor {
             this.telemetryLocalIdCount = 0;
         }
         assert(!session.isEmpty(), 0x757 /* Empty sessions should not be created. */);
+        this.eventEmitter.emit("rangeFinalized", range);
     }
     addEmptyCluster(session, capacity) {
         assert(!this.ongoingGhostSession?.cluster, 0x8a8 /* IdCompressor should not be operated normally when in a ghost session */);
@@ -436,24 +659,36 @@ export class IdCompressor {
                 sessionIndex++;
             }
         }
+        const sizeOfUuid = 2;
+        const shardingStateSize = hasLocalState && this.writeVersion >= SerializationVersion.V3
+            ? this.shardingState === undefined
+                ? 1 // Boolean: no sharding state
+                : 1 + // Boolean: has sharding state
+                    2 + // Numbers: currentStride, originalStride (Float64)
+                    1 + // Number: activeChildIds count (Float64)
+                    this.shardingState.activeChildIds.size * sizeOfUuid + // UUIDs: each is 128-bit
+                    1 + // Boolean: hasShardId
+                    (this.shardingState.shardId === undefined ? 0 : sizeOfUuid) // UUID: 128-bit if present
+            : 0;
         const localStateSize = hasLocalState
             ? 1 + // generated ID count
                 1 + // next range base genCount
                 1 + // count of normalizer pairs
-                normalizer.idRanges.size * 2 // pairs
+                normalizer.idRanges.size * 2 + // pairs
+                shardingStateSize // sharding state if present
             : 0;
         // Layout size, in 8 byte increments
         const totalSize = 1 + // version
             1 + // hasLocalState
             1 + // session count
             1 + // cluster count
-            sessionIndexMap.size * 2 + // session IDs
+            sessionIndexMap.size * sizeOfUuid + // session IDs
             finalSpace.clusters.length * 3 + // clusters: (sessionIndex, capacity, count)[]
             localStateSize; // local state, if present
         const serializedFloat = new Float64Array(totalSize);
         const serializedUint = new BigUint64Array(serializedFloat.buffer);
         let index = 0;
-        index = writeNumber(serializedFloat, index, currentWrittenVersion);
+        index = writeNumber(serializedFloat, index, this.writeVersion);
         index = writeBoolean(serializedFloat, index, hasLocalState);
         index = writeNumber(serializedFloat, index, sessionIndexMap.size);
         index = writeNumber(serializedFloat, index, finalSpace.clusters.length);
@@ -473,6 +708,24 @@ export class IdCompressor {
                 index = writeNumber(serializedFloat, index, leadingGenCount);
                 index = writeNumber(serializedFloat, index, count);
             }
+            // Write sharding state (version 3+)
+            if (this.writeVersion >= SerializationVersion.V3) {
+                index = writeBoolean(serializedFloat, index, this.shardingState !== undefined);
+                if (this.shardingState !== undefined) {
+                    index = writeNumber(serializedFloat, index, this.shardingState.currentStride);
+                    index = writeNumber(serializedFloat, index, this.shardingState.originalStride);
+                    // Write activeChildIds Set as count + array of NumericUuids
+                    index = writeNumber(serializedFloat, index, this.shardingState.activeChildIds.size);
+                    for (const childId of this.shardingState.activeChildIds) {
+                        index = writeNumericUuid(serializedUint, index, numericUuidFromStableId(childId));
+                    }
+                    // Write shardId (optional)
+                    index = writeBoolean(serializedFloat, index, this.shardingState.shardId !== undefined);
+                    if (this.shardingState.shardId !== undefined) {
+                        index = writeNumericUuid(serializedUint, index, numericUuidFromStableId(this.shardingState.shardId));
+                    }
+                }
+            }
         }
         assert(index === totalSize, 0x75b /* Serialized size was incorrectly calculated. */);
         logger?.sendTelemetryEvent({
@@ -484,27 +737,29 @@ export class IdCompressor {
         return bufferToString(serializedFloat.buffer, "base64");
     }
     static deserialize(params) {
-        const { serialized, newSessionId, logger } = params;
+        const { serialized, newSessionId: sessionId, logger, requestedWriteVersion } = params;
         const buffer = stringToBuffer(serialized, "base64");
         const index = {
             index: 0,
             bufferFloat: new Float64Array(buffer),
             bufferUint: new BigUint64Array(buffer),
         };
-        const version = readNumber(index);
-        switch (version) {
-            case 1: {
-                throw new Error("IdCompressor version 1.0 is no longer supported.");
-            }
-            case 2: {
-                return IdCompressor.deserialize2_0(index, newSessionId, logger);
+        const serializedVersion = readNumber(index);
+        // If requested version is < the serialized version, we must write the version serialized
+        // to avoid losing data.
+        const writeVersion = Math.max(requestedWriteVersion, serializedVersion);
+        switch (serializedVersion) {
+            case 2:
+            case 3: {
+                break;
             }
             default: {
+                if (serializedVersion === 1) {
+                    throw new Error("IdCompressor version 1.0 is no longer supported.");
+                }
                 throw new Error("Unknown IdCompressor serialized version.");
             }
         }
-    }
-    static deserialize2_0(index, sessionId, logger) {
         const hasLocalState = readBoolean(index);
         const sessionCount = readNumber(index);
         const clusterCount = readNumber(index);
@@ -525,7 +780,7 @@ export class IdCompressor {
             const numeric = readNumericUuid(index);
             sessions.push([numeric, new Session(numeric)]);
         }
-        const compressor = new IdCompressor(new Sessions(sessions), logger);
+        const compressor = new IdCompressor(new Sessions(sessions), logger, writeVersion);
         // Clusters
         let baseFinalId = 0;
         for (let i = 0; i < clusterCount; i++) {
@@ -547,6 +802,34 @@ export class IdCompressor {
             for (let i = 0; i < normalizerCount; i++) {
                 compressor.normalizer.addLocalRange(readNumber(index), readNumber(index));
             }
+            // Sharding state (version 3+)
+            if (serializedVersion >= 3) {
+                const hasShardingState = readBoolean(index);
+                if (hasShardingState) {
+                    const currentStride = readNumber(index);
+                    const originalStride = readNumber(index);
+                    // Read activeChildIds Set
+                    const activeChildCount = readNumber(index);
+                    const activeChildIds = new Set();
+                    for (let i = 0; i < activeChildCount; i++) {
+                        const childIdNumeric = readNumericUuid(index);
+                        // Safe cast: these were serialized as SessionIds
+                        activeChildIds.add(stableIdFromNumericUuid(childIdNumeric));
+                    }
+                    // Read shardId (optional)
+                    const hasShardId = readBoolean(index);
+                    const shardId = hasShardId
+                        ? stableIdFromNumericUuid(readNumericUuid(index))
+                        : undefined;
+                    // Build sharding state object, conditionally including shardId
+                    compressor.shardingState = {
+                        currentStride,
+                        originalStride,
+                        activeChildIds,
+                        ...(shardId !== undefined && { shardId }),
+                    };
+                }
+            }
         }
         assert(index.index === index.bufferFloat.length, 0x75f /* Failed to read entire serialized compressor. */);
         return compressor;
@@ -560,43 +843,101 @@ export class IdCompressor {
                 this.localGenCount !== other.localGenCount)) {
             return false;
         }
+        // Shard ownership affects future local ID allocation, even when the generated IDs match.
+        // It is not part of finalized state, so ignore it when comparing only that state.
+        if (includeLocalState) {
+            const state = this.shardingState;
+            const otherState = other.shardingState;
+            if (state === undefined || otherState === undefined) {
+                // Two unsharded compressors match here; a sharded and an unsharded compressor do not.
+                if (state !== otherState) {
+                    return false;
+                }
+            }
+            else {
+                if (state.currentStride !== otherState.currentStride ||
+                    state.originalStride !== otherState.originalStride ||
+                    state.shardId !== otherState.shardId ||
+                    state.activeChildIds.size !== otherState.activeChildIds.size) {
+                    return false;
+                }
+                // Child ownership is an unordered set. Equal sizes and membership imply equal sets,
+                // regardless of insertion order or whether the state was deserialized.
+                for (const childId of state.activeChildIds) {
+                    if (!otherState.activeChildIds.has(childId)) {
+                        return false;
+                    }
+                }
+            }
+        }
         return (this.sessions.equals(other.sessions, includeLocalState) &&
             this.finalSpace.equals(other.finalSpace));
     }
 }
-export function createIdCompressor(sessionIdOrLogger, loggerOrUndefined) {
+export function createIdCompressor(sessionIdOrDocumentVersion, writeVersionOrLogger, loggerOrUndefined) {
     let localSessionId;
+    let writeVersion;
     let logger;
-    if (sessionIdOrLogger === undefined) {
-        localSessionId = createSessionId();
+    if (typeof sessionIdOrDocumentVersion === "string") {
+        // Called with sessionId, writeVersion, logger?
+        localSessionId = sessionIdOrDocumentVersion;
+        writeVersion = writeVersionOrLogger;
+        logger = loggerOrUndefined;
     }
     else {
-        if (typeof sessionIdOrLogger === "string") {
-            localSessionId = sessionIdOrLogger;
-            logger = loggerOrUndefined;
-        }
-        else {
-            localSessionId = createSessionId();
-            logger = sessionIdOrLogger;
-        }
+        // Called with writeVersion, logger?
+        localSessionId = createSessionId();
+        writeVersion = sessionIdOrDocumentVersion;
+        logger = writeVersionOrLogger;
     }
-    const compressor = new IdCompressor(localSessionId, logger === undefined ? undefined : createChildLogger({ logger }));
+    const compressor = new IdCompressor(localSessionId, logger === undefined ? undefined : createChildLogger({ logger }), writeVersion);
     return compressor;
 }
-export function deserializeIdCompressor(serialized, sessionIdOrLogger, loggerOrUndefined) {
-    if (typeof sessionIdOrLogger === "string") {
+export function deserializeIdCompressor(serialized, sessionIdOrDocumentVersion, writeVersionOrLogger, loggerOrUndefined) {
+    if (typeof sessionIdOrDocumentVersion === "string") {
+        // Called with (serialized, sessionId, writeVersion, logger?)
         return IdCompressor.deserialize({
             serialized: serialized,
             logger: extractTelemetryLoggerExt(loggerOrUndefined),
-            newSessionId: sessionIdOrLogger,
+            newSessionId: sessionIdOrDocumentVersion,
+            requestedWriteVersion: writeVersionOrLogger,
         });
     }
     assert(loggerOrUndefined === undefined, 0xc2d /* logger would be in sessionIdOrLogger in this codepath */);
+    // Called with (serialized, writeVersion, logger?)
     return IdCompressor.deserialize({
         serialized: serialized,
-        logger: extractTelemetryLoggerExt(sessionIdOrLogger),
+        logger: extractTelemetryLoggerExt(writeVersionOrLogger),
+        requestedWriteVersion: sessionIdOrDocumentVersion,
     });
 }
+/**
+ * Throws an error indicating the compressor has been disposed.
+ */
+const throwDisposed = () => {
+    throw new Error("This compressor has been disposed via disposeShard() and can no longer be used.");
+};
+/**
+ * Makes an IdCompressor instance unusable by replacing all its methods with functions that throw.
+ * This is called once when disposeShard() is invoked to make the compressor permanently unusable.
+ * @param compressor - The compressor instance to make unusable
+ */
+function makeCompressorUnusable(compressor) {
+    // Get all method names from the prototype (where class methods live)
+    const proto = Object.getPrototypeOf(compressor);
+    for (const key of Reflect.ownKeys(proto)) {
+        if (key !== "constructor" && typeof Reflect.get(proto, key) === "function") {
+            // Shadow the method only on this instance so other compressors remain usable.
+            // Omitting `enumerable` keeps new overrides non-enumerable, like class methods.
+            // Reflection supports string and symbol keys without adding an index signature.
+            Object.defineProperty(compressor, key, {
+                value: throwDisposed,
+                configurable: true,
+                writable: true,
+            });
+        }
+    }
+}
 export function serializeIdCompressor(compressor, withSession) {
     const core = toIdCompressorWithCore(compressor);
     return withSession ? core.serialize(true) : core.serialize(false);