@fluidframework/container-runtime 2.0.0-dev.4.2.0.153917 → 2.0.0-dev.4.3.0.158678

package/lib/id-compressor/idCompressor.js

@@ -0,0 +1,1248 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { assert } from "@fluidframework/common-utils";
+import BTree from "sorted-btree";
+import { hasAtLeastLength, compareFiniteNumbers, compareFiniteNumbersReversed, compareMaps, compareStrings, fail, setPropertyIfDefined, } from "./utils";
+import { assertIsStableId, isStableId } from "./uuidUtilities";
+import { AppendOnlySortedMap } from "./appendOnlySortedMap";
+import { getIds } from "./idRange";
+import { numericUuidEquals, getPositiveDelta, incrementUuid, numericUuidFromStableId, stableIdFromNumericUuid, ensureSessionUuid, } from "./numericUuid";
+import { SessionIdNormalizer } from "./sessionIdNormalizer";
+/**
+ * Roughly equates to a minimum of 1M sessions before we start allocating 64 bit IDs.
+ * This value must *NOT* change without careful consideration to compatibility.
+ */
+export const defaultClusterCapacity = 512;
+/**
+ * The base UUID for the reserved id cluster.
+ * This should not be changed without consideration to compatibility.
+ */
+const reservedSessionId = ensureSessionUuid(assertIsStableId("decaf40b-3c1a-47f8-a7a1-e8461ddb69ce"));
+/**
+ * @returns true if the supplied ID is a final ID.
+ */
+export function isFinalId(id) {
+    return id >= 0;
+}
+/**
+ * @returns true if the supplied ID is a local ID.
+ */
+export function isLocalId(id) {
+    return id < 0;
+}
+/** Prepended to all keys in {@link IdCompressor.clustersAndOverridesInversion} that are override strings and not valid `StableIds` */
+const nonStableOverridePrefix = "\ue15e"; // A character in the Private Use Area of the BMP (https://en.wikipedia.org/wiki/Private_Use_Areas)
+/**
+ * See {@link IIdCompressor}
+ */
+export class IdCompressor {
+    /**
+     * @param localSessionId - the `IdCompressor`'s current local session ID.
+     * {@link generateStableId}.
+     */
+    constructor(localSessionId, logger) {
+        this.localSessionId = localSessionId;
+        this.logger = logger;
+        /**
+         * Trivially reach consensus on default cluster size and reserved IDs.
+         * These initial values must *NOT* change without careful consideration to compatibility.
+         */
+        this.newClusterCapacity = defaultClusterCapacity;
+        /**
+         * Session ID -\> data about the session's current cluster.
+         * Sessions are mutable, and thus should only be created via `createSession`.
+         */
+        this.sessions = new Map();
+        /**
+         * The base final ID of the next cluster to be created.
+         */
+        this.nextClusterBaseFinalId = 0;
+        /**
+         * Total number of IDs created locally during the current session.
+         */
+        this.localIdCount = 0;
+        /**
+         * Maps local IDs to override strings. This will contain an entry for every override assigned to a local ID generated during
+         * the current session, and retains entries for the lifetime of this compressor.
+         */
+        this.localOverrides = new AppendOnlySortedMap(compareFiniteNumbersReversed);
+        /**
+         * Maps local IDs to the final ID they are associated with (if any), and maps final IDs to the corresponding local ID (if any).
+         * This is used to efficiently compute normalization. This map can be thought of as mapping ranges of "optimistic uncertainty"
+         * (local IDs) to the result of consensus (reserved ranges of final IDs, a.k.a. clusters). Any given range of local IDs
+         * does not necessarily span an entire cluster, as some session-space IDs may be allocated *after* a cluster has been allocated
+         * but before it is full. In this case, there is no uncertainty, as the range of final IDs was reserved when the cluster was created.
+         * However, there is always a range of local IDs with size \>= 1 associated with the beginning of every cluster, as clusters are only
+         * created *after* they are needed and thus there is some period of uncertainty after local IDs have been handed out but before the
+         * range containing them has been finalized. There may also be ranges of local IDs that do not start at the beginning of a
+         * cluster; this happens when a cluster is expanded instead of allocating a new one.
+         * Additionally, session space IDs associated with an override string will also always be local IDs, because there is uncertainty as
+         * to whether another client simultaneously allocated the same override and could get sequenced first (a.k.a. unification) and its
+         * final ID would be associated with that override.
+         * See `SessionIdNormalizer` for more.
+         */
+        this.sessionIdNormalizer = new SessionIdNormalizer();
+        /**
+         * Contains entries for cluster base UUIDs and override strings (both local and final).
+         * As a performance optimization, entries for finalized strings also include the containing cluster object.
+         * This can be viewed as three separate tables: the inverse table for `localOverrides`, the inverse table for the union of all
+         * the overrides of the clusters in `finalIdToCluster`, and the inverse lookup of cluster base UUIDs to their clusters.
+         * This is unified as a performance optimization, as the common case does not have overridden IDs. It is a btree due to the need
+         * to make range queries.
+         */
+        this.clustersAndOverridesInversion = new BTree(undefined, compareStrings);
+        /**
+         * Maps the first final ID in a cluster to its owning cluster.
+         * Can be searched in O(log n) to determine clusters for any final ID.
+         */
+        this.finalIdToCluster = new AppendOnlySortedMap(compareFiniteNumbers);
+        this.localSession = this.createSession(localSessionId);
+    }
+    /**
+     * The size of each newly created ID cluster.
+     */
+    get clusterCapacity() {
+        return this.newClusterCapacity;
+    }
+    /**
+     * Must only be set with a value upon which consensus has been reached. Value must be greater than zero and less than
+     * `IdCompressor.maxClusterSize`.
+     */
+    set clusterCapacity(value) {
+        assert(value > 0, 0x481 /* Clusters must have a positive capacity */);
+        assert(value <= IdCompressor.maxClusterSize, 0x482 /* Clusters must not exceed max cluster size */);
+        this.newClusterCapacity = value;
+    }
+    /**
+     * Creates a session object for the supplied ID.
+     * Must only be called once per ID.
+     * @param sessionId - the ID for the session
+     * @returns the session object for the supplied ID
+     */
+    createSession(sessionId) {
+        assert(!this.clustersAndOverridesInversion.has(sessionId), 0x484 /* Attempted to create duplicate session */);
+        const existingSession = this.sessions.get(sessionId);
+        if (existingSession !== undefined) {
+            fail("createSession must only be called once for each session ID.");
+        }
+        const sessionUuid = numericUuidFromStableId(sessionId);
+        const session = {
+            sessionUuid,
+            currentClusterDetails: undefined,
+            lastFinalizedLocalId: undefined,
+        };
+        this.sessions.set(sessionId, session);
+        return session;
+    }
+    /**
+     * Returns a range of local IDs created by this session in a format for sending to the server for finalizing.
+     * The range will include all local IDs generated via calls to `generateCompressedId` since the last time this method was called.
+     * @returns the range of session-local IDs, which may be empty. This range must be sent to the server for ordering before
+     * it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method.
+     */
+    takeNextCreationRange() {
+        var _a;
+        const lastLocalInRange = -this.localIdCount;
+        const lastTakenNormalized = (_a = this.lastTakenLocalId) !== null && _a !== void 0 ? _a : 0;
+        assert(lastLocalInRange <= lastTakenNormalized, 0x485 /* Inconsistent local ID state */);
+        let ids;
+        if (lastLocalInRange !== lastTakenNormalized) {
+            const firstLocalInRange = (lastTakenNormalized - 1);
+            const overrides = [
+                ...this.localOverrides.getRange((lastTakenNormalized - 1), lastLocalInRange),
+            ];
+            if (hasAtLeastLength(overrides, 1)) {
+                assert(overrides[0][0] <= firstLocalInRange, 0x486 /* Inconsistent override state */);
+                assert(overrides[overrides.length - 1][0] >= lastLocalInRange, 0x487 /* Inconsistent override state */);
+                ids = {
+                    overrides,
+                };
+                const first = firstLocalInRange === overrides[0][0] ? undefined : firstLocalInRange;
+                const last = lastLocalInRange === overrides[overrides.length - 1][0]
+                    ? undefined
+                    : lastLocalInRange;
+                setPropertyIfDefined(first, ids, "first");
+                setPropertyIfDefined(last, ids, "last");
+            }
+            else {
+                ids = {
+                    first: firstLocalInRange,
+                    last: lastLocalInRange,
+                };
+            }
+            this.lastTakenLocalId = lastLocalInRange;
+        }
+        const range = { sessionId: this.localSessionId };
+        if (ids === undefined) {
+            return range;
+        }
+        assert(this.lastTakenLocalId === -this.localIdCount &&
+            this.lastTakenLocalId !== lastTakenNormalized, 0x488 /* Non-empty range must properly consume local IDs */);
+        range.ids = ids;
+        return range;
+    }
+    /**
+     * Finalizes the supplied range of IDs (which may be from either a remote or local session).
+     * @param range - the range of session-local IDs to finalize.
+     */
+    finalizeCreationRange(range) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+        const { sessionId } = range;
+        const isLocal = sessionId === this.localSessionId;
+        const session = (_a = this.sessions.get(sessionId)) !== null && _a !== void 0 ? _a : this.createSession(sessionId);
+        const ids = getIds(range);
+        if (ids === undefined) {
+            return;
+        }
+        const { currentClusterDetails } = session;
+        const { cluster: currentCluster, clusterBase: currentBaseFinalId } = currentClusterDetails !== null && currentClusterDetails !== void 0 ? currentClusterDetails : {
+            cluster: undefined,
+            clusterBase: undefined,
+        };
+        const currentClusterExists = currentCluster !== undefined && currentBaseFinalId !== undefined;
+        const normalizedLastFinalizedLocal = (_b = session.lastFinalizedLocalId) !== null && _b !== void 0 ? _b : 0;
+        const { first: newFirstFinalizedLocal, last: newLastFinalizedLocal } = ids;
+        assert(newFirstFinalizedLocal === normalizedLastFinalizedLocal - 1, 0x489 /* Ranges finalized out of order. */);
+        // The total number of session-local IDs to finalize
+        const finalizeCount = normalizedLastFinalizedLocal - newLastFinalizedLocal;
+        assert(finalizeCount >= 1, 0x48a /* Cannot finalize an empty range. */);
+        let eagerFinalIdCount = 0;
+        let initialClusterCount = 0;
+        let remainingCount = finalizeCount;
+        let newBaseUuid;
+        if (currentClusterExists) {
+            if (isLocal) {
+                const lastKnownFinal = (_c = this.sessionIdNormalizer.getLastFinalId()) !== null && _c !== void 0 ? _c : fail("Cluster exists but normalizer does not have an entry for it.");
+                const lastAlignedFinalInCluster = (currentBaseFinalId +
+                    Math.min(currentCluster.count + finalizeCount, currentCluster.capacity) -
+                    1);
+                if (lastAlignedFinalInCluster > lastKnownFinal) {
+                    this.sessionIdNormalizer.addFinalIds((lastKnownFinal + 1), lastAlignedFinalInCluster, currentCluster);
+                }
+            }
+            initialClusterCount = currentCluster.count;
+            const remainingCapacity = currentCluster.capacity - initialClusterCount;
+            const overflow = remainingCount - remainingCapacity;
+            const hasRoom = overflow <= 0;
+            if (hasRoom || currentBaseFinalId === this.finalIdToCluster.maxKey()) {
+                currentCluster.count += remainingCount;
+                eagerFinalIdCount = remainingCount;
+                remainingCount = 0;
+                // The common case is that there is room in the cluster, and the new final IDs can simply be added to it
+                if (!hasRoom) {
+                    // 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);
+                    assert(this.nextClusterBaseFinalId < Number.MAX_SAFE_INTEGER, 0x48b /* The number of allocated final IDs must not exceed the JS maximum safe integer. */);
+                    this.checkClusterForCollision(currentCluster);
+                    if (isLocal) {
+                        // Example with cluster size of 3:
+                        // Ids generated so far:   -1  1  2 -4 -5  <-- note positive numbers are eager finals
+                        //         Cluster:      [  0  1  2 ]
+                        // ~ finalizing happens, causing expansion of 2 (overflow) + 3 (cluster capacity) ~
+                        //        Cluster:       [  0  1  2  3  4  _  _  _ ]
+                        // corresponding locals:   -1       -4 -5
+                        //      lastFinalizedLocalId^           ^newLastFinalizedLocalId = -5
+                        //                  overflow = 2:    ----
+                        //                       localIdPivot^
+                        //                    lastFinalizedFinal^
+                        const newLastFinalizedFinal = (currentBaseFinalId +
+                            currentCluster.count -
+                            1);
+                        assert(session.lastFinalizedLocalId !== undefined, 0x48c /* Cluster already exists for session but there is no finalized local ID */);
+                        const finalPivot = (newLastFinalizedFinal -
+                            overflow +
+                            1);
+                        // Inform the normalizer of all IDs that we now know will end up being finalized into this cluster, including the ones
+                        // that were given out as locals (non-eager) because they exceeded the bounds of the current cluster before it was expanded.
+                        // It is safe to associate the unfinalized locals with their future final IDs even before the ranges for those locals are
+                        // actually finalized, because total order broadcast guarantees that any usage of those final IDs will be observed after
+                        // the finalization of the ranges.
+                        this.sessionIdNormalizer.registerFinalIdBlock(finalPivot, expansionAmount, currentCluster);
+                        (_d = this.logger) === null || _d === void 0 ? void 0 : _d.sendTelemetryEvent({
+                            eventName: "RuntimeIdCompressor:ClusterExpansion",
+                            sessionId: this.localSessionId,
+                            previousCapacity,
+                            newCapacity: currentCluster.capacity,
+                            overflow,
+                        });
+                    }
+                }
+            }
+            else {
+                // The range cannot be fully allocated in the existing cluster, so allocate any space left in it and
+                // form a new one by incrementing the previous baseUuid
+                newBaseUuid = incrementUuid(currentCluster.baseUuid, currentCluster.capacity);
+                currentCluster.count += remainingCapacity;
+                remainingCount -= remainingCapacity;
+                (_e = this.logger) === null || _e === void 0 ? void 0 : _e.sendTelemetryEvent({
+                    eventName: "RuntimeIdCompressor: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;
+            if (isLocal) {
+                (_f = this.logger) === null || _f === void 0 ? void 0 : _f.sendTelemetryEvent({
+                    eventName: "RuntimeIdCompressor:FirstCluster",
+                    sessionId: this.localSessionId,
+                });
+            }
+        }
+        // Finalizing a range results in one of three cases:
+        // 1. All local IDs are finalized into a new cluster (because there was either never a cluster for that session, or the current
+        //		cluster for the session was full).
+        // 2. All local IDs are finalized into the existing (current) cluster for the session.
+        // 3. Local IDs are finalized into both the current cluster and a new one, as the current cluster did not have enough room.
+        let newCluster;
+        let newBaseFinalId;
+        // The first local ID that will be finalized into a new cluster, if there is one.
+        // This lets us quickly compare which cluster an override string will go into.
+        let localIdPivot;
+        // Need to make a new cluster
+        if (newBaseUuid !== undefined) {
+            if (remainingCount <= 0) {
+                fail("Should not create an empty cluster.");
+            }
+            if (currentCluster !== undefined && currentCluster.capacity !== currentCluster.count) {
+                fail("Cluster must be filled before another is allocated.");
+            }
+            newBaseFinalId = this.nextClusterBaseFinalId;
+            const newCapacity = Math.max(this.newClusterCapacity, remainingCount);
+            newCluster = {
+                baseUuid: newBaseUuid,
+                capacity: newCapacity,
+                count: remainingCount,
+                session,
+            };
+            const usedCapacity = finalizeCount - remainingCount;
+            localIdPivot = (newFirstFinalizedLocal - usedCapacity);
+            if (isLocal) {
+                (_g = this.logger) === null || _g === void 0 ? void 0 : _g.sendTelemetryEvent({
+                    eventName: "RuntimeIdCompressor:NewCluster",
+                    sessionId: this.localSessionId,
+                    clusterCapacity: newCapacity,
+                    clusterCount: remainingCount,
+                });
+                this.sessionIdNormalizer.registerFinalIdBlock(newBaseFinalId, newCluster.capacity, newCluster);
+            }
+            this.checkClusterForCollision(newCluster);
+            this.clustersAndOverridesInversion.set(stableIdFromNumericUuid(newCluster.baseUuid), {
+                clusterBase: newBaseFinalId,
+                cluster: newCluster,
+            });
+            session.currentClusterDetails = { cluster: newCluster, clusterBase: newBaseFinalId };
+            this.nextClusterBaseFinalId = (this.nextClusterBaseFinalId +
+                newCluster.capacity);
+            assert(this.nextClusterBaseFinalId < Number.MAX_SAFE_INTEGER, 0x48e /* The number of allocated final IDs must not exceed the JS maximum safe integer. */);
+            this.finalIdToCluster.append(newBaseFinalId, newCluster);
+        }
+        // If there are overrides, we must determine which cluster object (current or overflow) each belongs to and add it.
+        const overrides = ids.overrides;
+        if (overrides !== undefined) {
+            for (let i = 0; i < overrides.length; i++) {
+                const [overriddenLocal, override] = overrides[i];
+                // Note: recall that local IDs are negative
+                assert(i === 0 || overriddenLocal < overrides[i - 1][0], 0x48f /* Override IDs must be in sorted order. */);
+                assert(overriddenLocal < normalizedLastFinalizedLocal, 0x490 /* Ranges finalized out of order. */);
+                assert(overriddenLocal >= newLastFinalizedLocal, 0x491 /* Malformed range: override ID ahead of range start. */);
+                let cluster;
+                let overriddenFinal;
+                if (localIdPivot !== undefined && overriddenLocal <= localIdPivot) {
+                    // Override is at or past the pivot, so it is in a new cluster.
+                    assert(newCluster !== undefined && newBaseFinalId !== undefined, 0x492 /* No cluster was created when overflow occurred. */);
+                    cluster = newCluster;
+                    overriddenFinal = (newBaseFinalId +
+                        (localIdPivot - overriddenLocal));
+                }
+                else {
+                    // Override was finalized into an existing cluster
+                    assert(currentCluster !== undefined && currentBaseFinalId !== undefined, 0x493 /* No cluster exists but IDs were finalized. */);
+                    cluster = currentCluster;
+                    overriddenFinal = (currentBaseFinalId +
+                        initialClusterCount +
+                        (normalizedLastFinalizedLocal - overriddenLocal) -
+                        1);
+                }
+                (_h = cluster.overrides) !== null && _h !== void 0 ? _h : (cluster.overrides = new Map());
+                const inversionKey = IdCompressor.createInversionKey(override);
+                const existingIds = this.getExistingIdsForNewOverride(inversionKey, true);
+                let overrideForCluster;
+                let associatedLocal;
+                if (existingIds !== undefined) {
+                    let mostFinalExistingOverride;
+                    if (typeof existingIds === "number") {
+                        mostFinalExistingOverride = existingIds;
+                        if (isLocalId(mostFinalExistingOverride)) {
+                            associatedLocal = mostFinalExistingOverride;
+                        }
+                    }
+                    else {
+                        [associatedLocal, mostFinalExistingOverride] = existingIds;
+                    }
+                    if (isFinalId(mostFinalExistingOverride)) {
+                        // A previous range already finalized an ID with this override. See `IdCluster` for more.
+                        overrideForCluster = mostFinalExistingOverride;
+                    }
+                    else {
+                        assert(!isLocal || mostFinalExistingOverride === overriddenLocal, 0x494 /* Cannot have multiple local IDs with identical overrides. */);
+                        // This session has created an ID with this override before, but has not finalized it yet. The incoming
+                        // range "wins" and will contain the final ID associated with that override, regardless of if that range was
+                        // made by this session or not.
+                        overrideForCluster = override;
+                    }
+                }
+                else {
+                    // This is the first time this override has been associated with any ID
+                    overrideForCluster = override;
+                }
+                assert(!cluster.overrides.has(overriddenFinal), 0x495 /* Cannot add a second override for final id */);
+                if (typeof overrideForCluster === "string") {
+                    if (isLocal || associatedLocal === undefined) {
+                        cluster.overrides.set(overriddenFinal, override);
+                    }
+                    else {
+                        cluster.overrides.set(overriddenFinal, {
+                            override,
+                            originalOverridingFinal: overriddenFinal,
+                            associatedLocalId: associatedLocal,
+                        });
+                    }
+                }
+                else {
+                    const unifiedOverride = {
+                        override,
+                        originalOverridingFinal: overrideForCluster,
+                    };
+                    setPropertyIfDefined(associatedLocal, unifiedOverride, "associatedLocalId");
+                    cluster.overrides.set(overriddenFinal, unifiedOverride);
+                }
+                const finalizedOverride = {
+                    cluster,
+                    originalOverridingFinal: overriddenFinal,
+                };
+                setPropertyIfDefined(associatedLocal, finalizedOverride, "associatedLocalId");
+                const currentOverride = this.clustersAndOverridesInversion.get(inversionKey);
+                if (currentOverride === undefined ||
+                    IdCompressor.isUnfinalizedOverride(currentOverride)) {
+                    // Update the map to contain a finalized override, but never update it with future finalized overrides with
+                    // the same string; those should decompress to the first final ID with that override.
+                    this.clustersAndOverridesInversion.set(inversionKey, finalizedOverride);
+                }
+            }
+        }
+        if (isLocal) {
+            (_j = this.logger) === null || _j === void 0 ? void 0 : _j.sendTelemetryEvent({
+                eventName: "RuntimeIdCompressor:IdCompressorStatus",
+                eagerFinalIdCount: eagerFinalIdCount - ((_k = overrides === null || overrides === void 0 ? void 0 : overrides.length) !== null && _k !== void 0 ? _k : 0),
+                localIdCount: remainingCount + ((_l = overrides === null || overrides === void 0 ? void 0 : overrides.length) !== null && _l !== void 0 ? _l : 0),
+                overridesCount: (_m = overrides === null || overrides === void 0 ? void 0 : overrides.length) !== null && _m !== void 0 ? _m : 0,
+                sessionId: this.localSessionId,
+            });
+        }
+        session.lastFinalizedLocalId = newLastFinalizedLocal;
+    }
+    checkClusterForCollision(cluster) {
+        const maxClusterUuid = incrementUuid(cluster.baseUuid, cluster.capacity - 1);
+        const maxClusterStableId = stableIdFromNumericUuid(maxClusterUuid);
+        const closestMatch = this.clustersAndOverridesInversion.getPairOrNextLower(maxClusterStableId);
+        if (closestMatch !== undefined) {
+            const [inversionKey, compressionMapping] = closestMatch;
+            if (!IdCompressor.isClusterInfo(compressionMapping)) {
+                if (isStableId(inversionKey) &&
+                    IdCompressor.uuidsMightCollide(inversionKey, maxClusterStableId, cluster.capacity)) {
+                    const numericOverride = numericUuidFromStableId(inversionKey);
+                    const delta = getPositiveDelta(maxClusterUuid, numericOverride, cluster.capacity - 1);
+                    if (delta !== undefined) {
+                        IdCompressor.failWithCollidingOverride(inversionKey);
+                    }
+                }
+            }
+        }
+    }
+    static failWithCollidingOverride(override) {
+        fail(`Override '${override}' collides with another allocated UUID.`);
+    }
+    static isClusterInfo(compressionMapping) {
+        return compressionMapping.clusterBase !== undefined;
+    }
+    static isUnfinalizedOverride(compressionMapping) {
+        return typeof compressionMapping === "number";
+    }
+    static createInversionKey(inversionKey) {
+        return isStableId(inversionKey)
+            ? inversionKey
+            : `${nonStableOverridePrefix}${inversionKey}`;
+    }
+    static isStableInversionKey(inversionKey) {
+        return inversionKey.charAt(0) !== nonStableOverridePrefix;
+    }
+    /**
+     * Returns an existing ID associated with an override, or undefined if none exists.
+     */
+    getExistingIdsForNewOverride(inversionKey, isFinalOverride) {
+        var _a;
+        const closestMatch = this.clustersAndOverridesInversion.getPairOrNextLower(inversionKey, reusedArray);
+        let numericOverride;
+        let stableOverride;
+        if (closestMatch !== undefined) {
+            const [key, compressionMapping] = closestMatch;
+            if (!IdCompressor.isClusterInfo(compressionMapping)) {
+                if (key === inversionKey) {
+                    if (IdCompressor.isUnfinalizedOverride(compressionMapping)) {
+                        return compressionMapping;
+                    }
+                    const finalizedOverride = compressionMapping;
+                    return finalizedOverride.associatedLocalId !== undefined
+                        ? [
+                            finalizedOverride.associatedLocalId,
+                            finalizedOverride.originalOverridingFinal,
+                        ]
+                        : finalizedOverride.originalOverridingFinal;
+                }
+            }
+            else if (IdCompressor.isStableInversionKey(inversionKey)) {
+                stableOverride = inversionKey;
+                const cluster = compressionMapping.cluster;
+                if (IdCompressor.uuidsMightCollide(inversionKey, key, cluster.capacity)) {
+                    numericOverride = numericUuidFromStableId(stableOverride);
+                    const delta = getPositiveDelta(numericOverride, cluster.baseUuid, cluster.capacity - 1);
+                    if (delta !== undefined) {
+                        if (!isFinalOverride) {
+                            if (delta >= cluster.count) {
+                                // TODO:#283: Properly implement unification
+                                return undefined;
+                            }
+                            return this.normalizeToSessionSpace((compressionMapping.clusterBase + delta));
+                        }
+                    }
+                }
+            }
+        }
+        const override = (_a = numericOverride !== null && numericOverride !== void 0 ? numericOverride : stableOverride) !== null && _a !== void 0 ? _a : (IdCompressor.isStableInversionKey(inversionKey) ? inversionKey : undefined);
+        if (override !== undefined) {
+            const sessionSpaceId = this.getCompressedIdForStableId(override);
+            if (sessionSpaceId !== undefined) {
+                return sessionSpaceId;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Check if `a` might be within `range` of `b`, where both are treated as hex numbers.
+     * @param range - an integer
+     */
+    static uuidsMightCollide(a, b, range) {
+        // Check if any of the UUIDs in the cluster collide (i.e. any in [base, base + capacity)).
+        // Optimization: All UUIDs in a cluster are the same string up until the last few characters which encode the offset from
+        // the cluster base. So, first compute the length of that shared string, and early out if it is different from the override
+        // UUID. This way we usually need not do the more expensive check below.
+        const hexDigitsToCheck = 32 - Math.ceil(Math.log2(range) / 2);
+        if (a.startsWith(b.slice(0, hexDigitsToCheck))) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Helper for retrieving an override.
+     */
+    static tryGetOverride(cluster, finalId) {
+        var _a;
+        const override = (_a = cluster.overrides) === null || _a === void 0 ? void 0 : _a.get(finalId);
+        if (override === undefined) {
+            return undefined;
+        }
+        if (typeof override === "string") {
+            return override;
+        }
+        return override.override;
+    }
+    /**
+     * Generates a new compressed ID or returns an existing one.
+     * This should ONLY be called to generate IDs for local operations.
+     * @param override - Specifies a specific string to be associated with the returned compressed ID.
+     * Performance note: assigning override strings incurs a performance overhead.
+     * @returns an existing ID if one already exists for `override`, and a new local ID otherwise. The returned ID is in session space.
+     */
+    generateCompressedId(override) {
+        let overrideInversionKey;
+        if (override !== undefined) {
+            overrideInversionKey = IdCompressor.createInversionKey(override);
+            const existingIds = this.getExistingIdsForNewOverride(overrideInversionKey, false);
+            if (existingIds !== undefined) {
+                return typeof existingIds === "number" ? existingIds : existingIds[0];
+            }
+        }
+        // Bump local counter regardless, then attempt to optimistically return a final ID.
+        // If the local session has reserved a cluster range via consensus, it is safe to hand out final IDs prior to
+        // finalizing the range that includes these locals.
+        const newLocalId = -++this.localIdCount;
+        const { currentClusterDetails } = this.localSession;
+        const { sessionIdNormalizer } = this;
+        let eagerFinalId;
+        let cluster;
+        if (currentClusterDetails !== undefined) {
+            cluster = currentClusterDetails.cluster;
+            const lastFinalKnown = sessionIdNormalizer.getLastFinalId();
+            if (lastFinalKnown !== undefined &&
+                lastFinalKnown - currentClusterDetails.clusterBase + 1 < cluster.capacity) {
+                eagerFinalId = (lastFinalKnown + 1);
+            }
+        }
+        if (overrideInversionKey !== undefined) {
+            const registeredLocal = sessionIdNormalizer.addLocalId();
+            assert(registeredLocal === newLocalId, 0x496 /* Session ID Normalizer produced unexpected local ID */);
+            if (eagerFinalId !== undefined) {
+                sessionIdNormalizer.addFinalIds(eagerFinalId, eagerFinalId, cluster !== null && cluster !== void 0 ? cluster : fail("No cluster when generating compressed ID"));
+            }
+            this.localOverrides.append(newLocalId, override !== null && override !== void 0 ? override : fail("Override must be defined"));
+            // Since the local ID was just created, it is in both session and op space
+            const compressionMapping = newLocalId;
+            this.clustersAndOverridesInversion.set(overrideInversionKey, compressionMapping);
+        }
+        else if (eagerFinalId !== undefined) {
+            sessionIdNormalizer.addFinalIds(eagerFinalId, eagerFinalId, cluster !== null && cluster !== void 0 ? cluster : fail("No cluster when generating compressed ID"));
+            return eagerFinalId;
+        }
+        else {
+            const registeredLocal = sessionIdNormalizer.addLocalId();
+            assert(registeredLocal === newLocalId, 0x497 /* Session ID Normalizer produced unexpected local ID */);
+        }
+        return newLocalId;
+    }
+    /**
+     * Decompresses a previously compressed ID into a UUID or override string.
+     * @param id - the compressed ID to be decompressed.
+     * @returns the UUID or override string associated with the compressed ID. Fails if the ID was not generated by this compressor.
+     */
+    decompress(id) {
+        var _a;
+        return (_a = this.tryDecompress(id)) !== null && _a !== void 0 ? _a : fail("Compressed ID was not generated by this compressor");
+    }
+    /**
+     * Attempts to decompress a previously compressed ID into a UUID or override string.
+     * @param id - the compressed ID to be decompressed.
+     * @returns the UUID or override string associated with the compressed ID, or undefined if the ID was not generated by this compressor.
+     */
+    tryDecompress(id) {
+        var _a;
+        if (isFinalId(id)) {
+            const possibleCluster = this.getClusterForFinalId(id);
+            if (possibleCluster === undefined) {
+                // It may be an unfinalized eager final ID, so check with normalizer to get the offset from the session UUID
+                const creationIndex = this.sessionIdNormalizer.getCreationIndex(id);
+                if (creationIndex !== undefined) {
+                    return stableIdFromNumericUuid(this.localSession.sessionUuid, creationIndex);
+                }
+                return undefined;
+            }
+            else {
+                const [baseFinalId, cluster] = possibleCluster;
+                const override = IdCompressor.tryGetOverride(cluster, id);
+                if (override !== undefined) {
+                    return override;
+                }
+                else {
+                    const offsetInCluster = id - baseFinalId;
+                    return stableIdFromNumericUuid(cluster.baseUuid, offsetInCluster);
+                }
+            }
+        }
+        else {
+            const idOffset = -id; // Convert to a positive number
+            if (idOffset > this.localIdCount) {
+                // This local ID was never allocated.
+                return undefined;
+            }
+            // If this is a local ID with an override, then it must have been allocated on this machine and will be contained in
+            // `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 = (_a = this.localOverrides) === null || _a === void 0 ? void 0 : _a.get(id);
+            return localOverride !== undefined
+                ? localOverride
+                : stableIdFromNumericUuid(this.localSession.sessionUuid, idOffset - 1);
+        }
+    }
+    /**
+     * Recompresses a decompressed ID, which could be a UUID or an override string.
+     * @param uncompressed - the UUID or override string to recompress.
+     * @returns the `CompressedId` associated with `uncompressed`. Fails if it has not been previously compressed by this compressor.
+     */
+    recompress(uncompressed) {
+        var _a;
+        return (_a = this.tryRecompress(uncompressed)) !== null && _a !== void 0 ? _a : fail("No such string has ever been compressed");
+    }
+    /**
+     * Attempts to recompresses a decompressed ID, which could be a UUID or an override string.
+     * @param uncompressed - the UUID or override string to recompress,
+     * @returns the `CompressedId` associated with `uncompressed` or undefined if it has not been previously compressed by this compressor.
+     */
+    tryRecompress(uncompressed) {
+        return this.recompressInternal(uncompressed);
+    }
+    /**
+     * Helper to compress an uncompressed UUID. It can optionally be supplied with the numeric form of `uncompressedUuid` as a
+     * performance optimization.
+     */
+    recompressInternal(uncompressed, uncompressedUuidNumeric) {
+        var _a, _b;
+        let numericUuid = uncompressedUuidNumeric;
+        const inversionKey = IdCompressor.createInversionKey(uncompressed);
+        const isStable = IdCompressor.isStableInversionKey(inversionKey);
+        const closestMatch = this.clustersAndOverridesInversion.getPairOrNextLower(inversionKey, reusedArray);
+        if (closestMatch !== undefined) {
+            const [key, compressionMapping] = closestMatch;
+            if (!IdCompressor.isClusterInfo(compressionMapping)) {
+                if (key === inversionKey) {
+                    return IdCompressor.isUnfinalizedOverride(compressionMapping)
+                        ? compressionMapping
+                        : (_a = compressionMapping.associatedLocalId) !== null && _a !== void 0 ? _a : compressionMapping.originalOverridingFinal;
+                }
+            }
+            else {
+                if (!isStable) {
+                    return undefined;
+                }
+                const { clusterBase: closestBaseFinalId, cluster: closestCluster } = compressionMapping;
+                numericUuid !== null && numericUuid !== void 0 ? numericUuid : (numericUuid = numericUuidFromStableId(inversionKey));
+                const uuidOffset = getPositiveDelta(numericUuid, closestCluster.baseUuid, closestCluster.count - 1);
+                if (uuidOffset !== undefined) {
+                    let targetFinalId = (closestBaseFinalId + uuidOffset);
+                    const override = (_b = closestCluster.overrides) === null || _b === void 0 ? void 0 : _b.get(targetFinalId);
+                    if (typeof override === "object") {
+                        if (override.associatedLocalId !== undefined) {
+                            return override.associatedLocalId;
+                        }
+                        // This may be a UUID that should actually compress into a different final ID that it aligns with, due to
+                        // another session having an identical override (see `IdCluster` for more).
+                        targetFinalId = override.originalOverridingFinal;
+                    }
+                    return this.normalizeToSessionSpace(targetFinalId);
+                }
+            }
+        }
+        if (isStable) {
+            // May have already computed the numeric UUID, so avoid recomputing if possible
+            const sessionSpaceId = this.getCompressedIdForStableId(numericUuid !== null && numericUuid !== void 0 ? numericUuid : inversionKey);
+            if (sessionSpaceId !== undefined) {
+                return sessionSpaceId;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Normalizes a session space ID into op space.
+     * @param id - the local ID to normalize.
+     * @returns the ID in op space.
+     */
+    normalizeToOpSpace(id) {
+        var _a, _b, _c;
+        if (isFinalId(id)) {
+            return id;
+        }
+        // Check if this local ID has not been allocated yet
+        if (-id > this.localIdCount) {
+            fail("Supplied local ID was not created by this compressor.");
+        }
+        // Check if this local ID has not been finalized yet.
+        // Comparing lastFinalizedLocalId is a safe check for eager final IDs because the local IDs corresponding to them
+        // are never handed out to a consumer, and thus could not be passed into this method.
+        const { lastFinalizedLocalId } = this.localSession;
+        if (lastFinalizedLocalId === undefined || id < lastFinalizedLocalId) {
+            // Eager final IDs do not have overrides in the cluster until finalizing
+            // This means that using the normalizer to get the final/cluster associated would succeed but would not have the override,
+            // so checking localOverrides first is necessary.
+            const override = this.localOverrides.get(id);
+            if (override !== undefined) {
+                const inversionKey = IdCompressor.createInversionKey(override);
+                const compressionMapping = (_a = this.clustersAndOverridesInversion.get(inversionKey)) !== null && _a !== void 0 ? _a : fail("Bimap is malformed.");
+                return !IdCompressor.isClusterInfo(compressionMapping) &&
+                    !IdCompressor.isUnfinalizedOverride(compressionMapping) &&
+                    compressionMapping.associatedLocalId === id
+                    ? compressionMapping.originalOverridingFinal
+                    : id;
+            }
+            const possibleFinal = this.sessionIdNormalizer.getFinalId(id);
+            return (_b = possibleFinal === null || possibleFinal === void 0 ? void 0 : possibleFinal[0]) !== null && _b !== void 0 ? _b : id;
+        }
+        const [correspondingFinal, cluster] = (_c = this.sessionIdNormalizer.getFinalId(id)) !== null && _c !== void 0 ? _c : fail("Locally created cluster should be added to the map when allocated");
+        if (cluster.overrides) {
+            const override = cluster.overrides.get(correspondingFinal);
+            if (typeof override === "object" && override.originalOverridingFinal !== undefined) {
+                // Rare case of two local IDs with same overrides are created concurrently. See `IdCluster` for more.
+                return override.originalOverridingFinal;
+            }
+        }
+        return correspondingFinal;
+    }
+    normalizeToSessionSpace(id, sessionIdIfLocal) {
+        var _a, _b, _c, _d;
+        if (isLocalId(id)) {
+            if (sessionIdIfLocal === undefined || sessionIdIfLocal === this.localSessionId) {
+                const localIndex = -id;
+                if (localIndex > this.localIdCount) {
+                    fail("Supplied local ID was not created by this compressor.");
+                }
+                return id;
+            }
+            else {
+                const session = (_a = this.sessions.get(sessionIdIfLocal)) !== null && _a !== void 0 ? _a : fail("No IDs have ever been finalized by the supplied session.");
+                const localCount = -id;
+                const numericUuid = incrementUuid(session.sessionUuid, localCount - 1);
+                return ((_b = this.compressNumericUuid(numericUuid)) !== null && _b !== void 0 ? _b : fail("ID is not known to this compressor."));
+            }
+        }
+        const normalizedId = this.sessionIdNormalizer.getSessionSpaceId(id);
+        if (normalizedId !== undefined) {
+            return normalizedId;
+        }
+        // Check for a unified override finalized first by another session but to which the local session
+        // still has an associated local ID.
+        const [_, cluster] = (_c = this.getClusterForFinalId(id)) !== null && _c !== void 0 ? _c : fail("Supplied final ID was not finalized by this compressor.");
+        const override = (_d = cluster.overrides) === null || _d === void 0 ? void 0 : _d.get(id);
+        if (typeof override === "object" && override.associatedLocalId !== undefined) {
+            return override.associatedLocalId;
+        }
+        return id;
+    }
+    /**
+     * Returns the session-space compressed ID corresponding to the numeric UUID, or undefined if it is not known to this compressor.
+     * Typically, it will return the session-space ID sequentially aligned with it (which will be local if `numericUuid` was made by
+     * the local session, or final otherwise). However, in the event that the aligned session-space ID was overridden with a UUID
+     * *and* that override UUID was concurrently used in an older ID (earlier, w.r.t. sequencing), this method can return the first
+     * ID to correspond to that override.
+     *
+     * As an example, consider the following two clients:
+     * ClientA, session UUID: A0000000-0000-0000-0000-000000000000
+     * ClientB, session UUID: B0000000-0000-0000-0000-000000000000
+     *
+     * If concurrently, two clients performed:
+     * ClientA: generateCompressedId(override: 'X0000000-0000-0000-0000-000000000000') // aligned with A0000000-0000-0000-0000-000000000000
+     *
+     * ClientB: generateCompressedId() // aligned with B0000000-0000-0000-0000-000000000000
+     * ClientB: generateCompressedId(override: 'X0000000-0000-0000-0000-000000000000') // aligned with B0000000-0000-0000-0000-000000000001
+     *
+     * After sequencing, calling this method and passing the numeric UUID for B0000000-0000-0000-0000-000000000001 would return the
+     * session-space ID corresponding to A0000000-0000-0000-0000-000000000000 (with override X0000000-0000-0000-0000-000000000000).
+     */
+    compressNumericUuid(numericUuid) {
+        const stableId = stableIdFromNumericUuid(numericUuid);
+        const sessionSpaceId = this.recompressInternal(stableId, numericUuid);
+        if (sessionSpaceId === undefined) {
+            return undefined;
+        }
+        return sessionSpaceId;
+    }
+    /**
+     * Returns a compressed ID for the supplied stable ID if it was created by the local session, and undefined otherwise.
+     */
+    getCompressedIdForStableId(stableId) {
+        const numericUuid = typeof stableId === "string" ? numericUuidFromStableId(stableId) : stableId;
+        const creationIndex = getPositiveDelta(numericUuid, this.localSession.sessionUuid, this.localIdCount - 1);
+        if (creationIndex !== undefined) {
+            const sessionSpaceId = this.sessionIdNormalizer.getIdByCreationIndex(creationIndex);
+            if (sessionSpaceId !== undefined) {
+                return sessionSpaceId;
+            }
+        }
+        return undefined;
+    }
+    getClusterForFinalId(finalId) {
+        const possibleCluster = this.finalIdToCluster.getPairOrNextLower(finalId);
+        if (possibleCluster === undefined) {
+            return undefined;
+        }
+        const [clusterBase, cluster] = possibleCluster;
+        if (finalId - clusterBase >= cluster.count) {
+            return undefined;
+        }
+        return possibleCluster;
+    }
+    /**
+     * @returns if `other` is equal to this `IdCompressor`. The equality check includes local session state only if specified.
+     * \@testOnly
+     */
+    equals(other, compareLocalState) {
+        if (compareLocalState) {
+            if (this.localIdCount !== other.localIdCount ||
+                this.localSessionId !== other.localSessionId ||
+                this.lastTakenLocalId !== other.lastTakenLocalId) {
+                return false;
+            }
+            if (!this.localOverrides.equals(other.localOverrides, (a, b) => a === b)) {
+                return false;
+            }
+            if (!compareMaps(this.sessions, other.sessions, (a, b) => IdCompressor.sessionDataEqual(a, b, true, compareLocalState))) {
+                return false;
+            }
+            if (!this.sessionIdNormalizer.equals(other.sessionIdNormalizer, (a, b) => IdCompressor.idClustersEqual(a, b, false, compareLocalState))) {
+                return false;
+            }
+        }
+        else {
+            for (const [keyA, valueA] of this.sessions) {
+                const valueB = other.sessions.get(keyA);
+                if (valueB === undefined) {
+                    if (valueA.lastFinalizedLocalId !== undefined) {
+                        return false;
+                    }
+                }
+                else if (!IdCompressor.sessionDataEqual(valueA, valueB, true, compareLocalState)) {
+                    return false;
+                }
+            }
+            for (const [keyB, valueB] of other.sessions) {
+                const valueA = this.sessions.get(keyB);
+                if (valueA === undefined) {
+                    if (valueB.lastFinalizedLocalId !== undefined) {
+                        return false;
+                    }
+                }
+            }
+        }
+        if (this.nextClusterBaseFinalId !== other.nextClusterBaseFinalId ||
+            this.newClusterCapacity !== other.newClusterCapacity) {
+            return false;
+        }
+        if (!this.finalIdToCluster.equals(other.finalIdToCluster, (a, b) => IdCompressor.idClustersEqual(a, b, true, compareLocalState))) {
+            return false;
+        }
+        const missingInOne = (_, value) => {
+            if (!compareLocalState && IdCompressor.isUnfinalizedOverride(value)) {
+                return undefined;
+            }
+            return { break: true };
+        };
+        const compareCompressionMappings = (a, b) => {
+            const unfinalizedA = IdCompressor.isUnfinalizedOverride(a);
+            const unfinalizedB = IdCompressor.isUnfinalizedOverride(b);
+            if (unfinalizedA) {
+                if (unfinalizedB) {
+                    return a === b;
+                }
+                return false;
+            }
+            else if (unfinalizedB) {
+                return false;
+            }
+            if (IdCompressor.isClusterInfo(a)) {
+                if (!IdCompressor.isClusterInfo(b) || a.clusterBase !== b.clusterBase) {
+                    return false;
+                }
+            }
+            else {
+                if (IdCompressor.isClusterInfo(b) ||
+                    (compareLocalState && a.associatedLocalId !== b.associatedLocalId) ||
+                    a.originalOverridingFinal !== b.originalOverridingFinal) {
+                    return false;
+                }
+            }
+            if (!IdCompressor.idClustersEqual(a.cluster, b.cluster, true, compareLocalState)) {
+                return false;
+            }
+            return true;
+        };
+        const diff = this.clustersAndOverridesInversion.diffAgainst(other.clustersAndOverridesInversion, missingInOne, missingInOne, (_, valA, valB) => {
+            if (!compareCompressionMappings(valA, valB)) {
+                return { break: true };
+            }
+            return undefined;
+        });
+        return diff === undefined;
+    }
+    static sessionDataEqual(a, b, checkCluster = true, compareLocalState = true) {
+        if (!numericUuidEquals(a.sessionUuid, b.sessionUuid) ||
+            a.lastFinalizedLocalId !== b.lastFinalizedLocalId) {
+            return false;
+        }
+        if (a.currentClusterDetails === undefined || b.currentClusterDetails === undefined) {
+            if (a.currentClusterDetails !== b.currentClusterDetails) {
+                return false;
+            }
+            return true;
+        }
+        if (checkCluster &&
+            !IdCompressor.idClustersEqual(a.currentClusterDetails.cluster, b.currentClusterDetails.cluster, false, compareLocalState)) {
+            return false;
+        }
+        return true;
+    }
+    static idClustersEqual(a, b, checkSessionData = true, compareLocalState = true) {
+        var _a, _b;
+        const areEqual = numericUuidEquals(a.baseUuid, b.baseUuid) &&
+            a.capacity === b.capacity &&
+            a.count === b.count &&
+            (!checkSessionData ||
+                IdCompressor.sessionDataEqual(a.session, b.session, false, compareLocalState)) &&
+            (a.overrides === undefined) === (b.overrides === undefined) &&
+            (a.overrides === undefined ||
+                compareMaps((_a = a.overrides) !== null && _a !== void 0 ? _a : fail("Overrides must be defined"), (_b = b.overrides) !== null && _b !== void 0 ? _b : fail("Overrides must be defined"), (overrideA, overrideB) => {
+                    if (compareLocalState) {
+                        if (typeof overrideA === "string" || typeof overrideB === "string") {
+                            return overrideA === overrideB;
+                        }
+                        const overridesEqual = overrideA.override === overrideB.override &&
+                            overrideA.originalOverridingFinal ===
+                                overrideB.originalOverridingFinal &&
+                            (!compareLocalState ||
+                                overrideA.associatedLocalId === overrideB.associatedLocalId);
+                        return overridesEqual;
+                    }
+                    const uuidA = typeof overrideA === "string" ? overrideA : overrideA.override;
+                    const uuidB = typeof overrideB === "string" ? overrideB : overrideB.override;
+                    if (typeof overrideA !== "string" &&
+                        typeof overrideB !== "string" &&
+                        overrideA.originalOverridingFinal !== overrideB.originalOverridingFinal) {
+                        return false;
+                    }
+                    return uuidA === uuidB;
+                }));
+        return areEqual;
+    }
+    serialize(withSession) {
+        var _a, _b;
+        const serializedSessions = [];
+        const sessionIdToSessionIndex = new Map();
+        for (const [sessionId, session] of this.sessions) {
+            const isLocalSession = sessionId === this.localSessionId;
+            const includeSession = sessionId !== reservedSessionId && // Ignore reserved clusters, but
+                (session.lastFinalizedLocalId !== undefined || // always serialize sessions that made final IDs,
+                    (isLocalSession && withSession)); // include the un-acked local session if requested
+            if (includeSession) {
+                const sessionData = [sessionId];
+                sessionIdToSessionIndex.set(sessionId, serializedSessions.length);
+                serializedSessions.push(sessionData);
+            }
+        }
+        const serializedClusters = [];
+        for (const [baseFinalId, cluster] of this.finalIdToCluster.entries()) {
+            const sessionId = stableIdFromNumericUuid(cluster.session.sessionUuid);
+            if (sessionId !== reservedSessionId) {
+                const sessionIndex = (_a = sessionIdToSessionIndex.get(sessionId)) !== null && _a !== void 0 ? _a : fail("Session object contains wrong session numeric UUID");
+                const serializedCluster = [
+                    sessionIndex,
+                    cluster.capacity,
+                ];
+                if (cluster.count !== cluster.capacity) {
+                    serializedCluster.push(cluster.count);
+                }
+                if (cluster.overrides !== undefined) {
+                    const serializedOverrides = [];
+                    for (const [finalId, override] of cluster.overrides) {
+                        const finalIdIndex = finalId - baseFinalId;
+                        if (typeof override === "string") {
+                            serializedOverrides.push([finalIdIndex, override]);
+                        }
+                        else if (override.originalOverridingFinal === finalId) {
+                            serializedOverrides.push([finalIdIndex, override.override]);
+                        }
+                        else {
+                            serializedOverrides.push([
+                                finalIdIndex,
+                                override.override,
+                                override.originalOverridingFinal,
+                            ]);
+                        }
+                    }
+                    serializedCluster.push(serializedOverrides);
+                }
+                serializedClusters.push(serializedCluster);
+            }
+        }
+        // Reserved session not serialized, and local session is present but may not make IDs
+        assert(serializedSessions.length - this.sessions.size <= 2, 0x498 /* session not serialized */);
+        const serializedIdCompressor = {
+            version: currentWrittenVersion,
+            clusterCapacity: this.clusterCapacity,
+            sessions: serializedSessions,
+            clusters: serializedClusters,
+        };
+        if (withSession) {
+            const serializedWithSession = serializedIdCompressor;
+            serializedWithSession.localSessionIndex = serializedWithSession.sessions.findIndex(([sessionId]) => sessionId === this.localSessionId);
+            if (this.localIdCount > 0) {
+                serializedWithSession.localState = {
+                    localIdCount: this.localIdCount,
+                    overrides: [...this.localOverrides.entries()].map((entry) => [...entry]),
+                    lastTakenLocalId: this.lastTakenLocalId,
+                    sessionNormalizer: this.sessionIdNormalizer.serialize(),
+                };
+            }
+            return serializedWithSession;
+        }
+        (_b = this.logger) === null || _b === void 0 ? void 0 : _b.sendTelemetryEvent({
+            eventName: "RuntimeIdCompressor:SerializedIdCompressorSize",
+            size: JSON.stringify(serializedIdCompressor).length,
+            clusterCount: serializedIdCompressor.clusters.length,
+            sessionCount: serializedIdCompressor.sessions.length,
+        });
+        return serializedIdCompressor;
+    }
+    static deserialize(...args) {
+        const [serialized, newSessionIdMaybe] = args;
+        const { clusterCapacity, sessions: serializedSessions, clusters: serializedClusters, } = serialized;
+        let localSessionId;
+        let serializedLocalState;
+        if (newSessionIdMaybe === undefined) {
+            // Alias of serialized, but known to be a SerializedIdCompressorWithOngoingSession
+            const [serializedWithSession] = args;
+            const serializedSessionData = serializedSessions[serializedWithSession.localSessionIndex];
+            localSessionId = serializedSessionData[0];
+            serializedLocalState = serializedWithSession.localState;
+        }
+        else {
+            localSessionId = newSessionIdMaybe;
+        }
+        const compressor = new IdCompressor(localSessionId);
+        compressor.clusterCapacity = clusterCapacity;
+        const localOverridesInverse = new Map();
+        if (serializedLocalState !== undefined) {
+            // Do this part of local rehydration first since the cluster map population needs to query to local overrides
+            compressor.localIdCount = serializedLocalState.localIdCount;
+            compressor.lastTakenLocalId = serializedLocalState.lastTakenLocalId;
+            if (serializedLocalState.overrides !== undefined) {
+                for (const [localId, override] of serializedLocalState.overrides) {
+                    compressor.localOverrides.append(localId, override);
+                    localOverridesInverse.set(override, localId);
+                    compressor.clustersAndOverridesInversion.set(IdCompressor.createInversionKey(override), localId);
+                }
+            }
+        }
+        const sessionInfos = [];
+        for (const serializedSession of serializedSessions) {
+            const [sessionId] = serializedSession;
+            if (sessionId === localSessionId) {
+                assert(hasOngoingSession(serialized), 0x499 /* Cannot resume existing session. */);
+                sessionInfos.push({ session: compressor.localSession, sessionId });
+            }
+            else {
+                const session = compressor.createSession(sessionId);
+                sessionInfos.push({ session, sessionId });
+            }
+        }
+        for (const serializedCluster of serializedClusters) {
+            const { sessionIndex, capacity, count, overrides } = deserializeCluster(serializedCluster);
+            const { session, sessionId } = sessionInfos[sessionIndex];
+            const { lastFinalizedLocalId, sessionUuid } = session;
+            const currentIdCount = lastFinalizedLocalId === undefined ? 0 : -lastFinalizedLocalId;
+            const cluster = {
+                capacity,
+                count,
+                baseUuid: incrementUuid(sessionUuid, currentIdCount),
+                session,
+            };
+            const lastFinalizedNormalized = lastFinalizedLocalId !== null && lastFinalizedLocalId !== void 0 ? lastFinalizedLocalId : 0;
+            const clusterBase = compressor.nextClusterBaseFinalId;
+            session.lastFinalizedLocalId = (lastFinalizedNormalized - count);
+            session.currentClusterDetails = { clusterBase, cluster };
+            compressor.nextClusterBaseFinalId = (compressor.nextClusterBaseFinalId +
+                capacity);
+            compressor.finalIdToCluster.append(clusterBase, cluster);
+            compressor.clustersAndOverridesInversion.set(stableIdFromNumericUuid(cluster.baseUuid), {
+                clusterBase,
+                cluster,
+            });
+            if (overrides !== undefined) {
+                cluster.overrides = new Map();
+                for (const [finalIdIndex, override, originalOverridingFinal] of overrides) {
+                    const finalId = (clusterBase + finalIdIndex);
+                    if (originalOverridingFinal !== undefined) {
+                        const unifiedOverride = {
+                            override,
+                            originalOverridingFinal,
+                        };
+                        if (serializedLocalState !== undefined) {
+                            setPropertyIfDefined(localOverridesInverse.get(override), unifiedOverride, "associatedLocalId");
+                        }
+                        cluster.overrides.set(finalId, unifiedOverride);
+                    }
+                    else {
+                        const associatedLocal = localOverridesInverse.get(override);
+                        if (associatedLocal !== undefined && sessionId !== localSessionId) {
+                            // In this case, there is a local ID associated with this override, but this is the first cluster to contain
+                            // that override (because only the first cluster will have the string serialized). In this case, the override
+                            // needs to hold that local value.
+                            cluster.overrides.set(finalId, {
+                                override,
+                                originalOverridingFinal: finalId,
+                                associatedLocalId: associatedLocal,
+                            });
+                        }
+                        else {
+                            cluster.overrides.set(finalId, override);
+                        }
+                        const finalizedOverride = {
+                            cluster,
+                            originalOverridingFinal: finalId,
+                        };
+                        if (serializedLocalState !== undefined) {
+                            setPropertyIfDefined(associatedLocal, finalizedOverride, "associatedLocalId");
+                        }
+                        compressor.clustersAndOverridesInversion.set(IdCompressor.createInversionKey(override), finalizedOverride);
+                    }
+                }
+            }
+        }
+        if (serializedLocalState !== undefined) {
+            compressor.sessionIdNormalizer = SessionIdNormalizer.deserialize(serializedLocalState.sessionNormalizer, (finalId) => {
+                var _a;
+                const [_, cluster] = (_a = compressor.finalIdToCluster.getPairOrNextLower(finalId)) !== null && _a !== void 0 ? _a : fail("Final in serialized normalizer was never created.");
+                return cluster;
+            });
+        }
+        assert(compressor.localSession.lastFinalizedLocalId === undefined ||
+            compressor.localIdCount >= -compressor.localSession.lastFinalizedLocalId, 0x49a /* Inconsistent last finalized state when deserializing */);
+        return compressor;
+    }
+    static convertToCurrentVersion(serializedCompressor, hasSession) {
+        if (serializedCompressor.version !== currentWrittenVersion) {
+            fail("Unknown SerializedIdCompressor version number");
+        }
+        const serialized = serializedCompressor;
+        if (hasSession !== hasOngoingSession(serialized)) {
+            return undefined;
+        }
+        return serialized;
+    }
+}
+/**
+ * Max allowed cluster size
+ */
+IdCompressor.maxClusterSize = 2 ** 20;
+/**
+ * The version of `IdCompressor` that is currently persisted.
+ */
+const currentWrittenVersion = "0.0.1";
+/**
+ * @returns whether or not the given serialized ID compressor has an ongoing session.
+ */
+export function hasOngoingSession(serialized) {
+    return (serialized.localSessionIndex !==
+        undefined);
+}
+function deserializeCluster(serializedCluster) {
+    const [sessionIndex, capacity, countOrOverrides, overrides] = serializedCluster;
+    const hasCount = typeof countOrOverrides === "number";
+    return {
+        sessionIndex,
+        capacity,
+        count: hasCount ? countOrOverrides : capacity,
+        overrides: hasCount ? overrides : countOrOverrides,
+    };
+}
+/**
+ * Optimization used by the sorted-btree library to avoid allocating tuples every time a lookup method is called.
+ * Lookup methods on BTree accept a pre-allocated array that it populates with the result of the lookup and retains no ownership
+ * of after the call, so this array may be supplied to any of them. References to this array should not be retained elsewhere and
+ * lookup results should be extracted from the tuple immediately after invocation.
+ */
+const reusedArray = [];
+//# sourceMappingURL=idCompressor.js.map