@fluid-experimental/tree 0.58.2001 → 0.59.1000-61898

package/dist/id-compressor/IdCompressor.js

@@ -0,0 +1,1353 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasOngoingSession = exports.IdCompressor = exports.isLocalId = exports.isFinalId = exports.legacySharedTreeInitialTreeId = exports.defaultClusterCapacity = void 0;
+/* eslint-disable @typescript-eslint/restrict-plus-operands */
+const sorted_btree_1 = __importDefault(require("sorted-btree"));
+const Common_1 = require("../Common");
+const AppendOnlySortedMap_1 = require("./AppendOnlySortedMap");
+const IdRange_1 = require("./IdRange");
+const NumericUuid_1 = require("./NumericUuid");
+/**
+ * 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.
+ */
+exports.defaultClusterCapacity = 512;
+/**
+ * The base UUID for the reserved id cluster.
+ * This should not be changed without consideration to compatibility.
+ */
+const reservedSessionId = NumericUuid_1.ensureSessionUuid(NumericUuid_1.assertIsStableId('decaf40b-3c1a-47f8-a7a1-e8461ddb69ce'));
+/**
+ * The ID override for the initial tree of a SharedTree. An artifact of an unfortunate typo which included an extraneous '6' on the UUID
+ * which must be forever preserved for backwards compatibility.
+ */
+exports.legacySharedTreeInitialTreeId = `24e26f0b-3c1a-47f8-a7a1-e8461ddb69ce6`;
+/**
+ * @returns true if the supplied ID is a final ID.
+ */
+function isFinalId(id) {
+    return id >= 0;
+}
+exports.isFinalId = isFinalId;
+/**
+ * @returns true if the supplied ID is a local ID.
+ */
+function isLocalId(id) {
+    return id < 0;
+}
+exports.isLocalId = isLocalId;
+/** 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)
+/**
+ * A distributed UUID generator and compressor.
+ *
+ * Generates arbitrary non-colliding v4 UUIDs, called stable IDs, for multiple "sessions" (which can be distributed across the network),
+ * providing each session with the ability to map these UUIDs to `numbers`.
+ *
+ * A session is a unique identifier that denotes a single compressor. New IDs are created through a single compressor API
+ * which should then sent in ranges to the server for total ordering (and are subsequently relayed to other clients). When a new ID is
+ * created it is said to be created by the compressor's "local" session.
+ *
+ * For each stable ID created, two numeric IDs are provided by the compressor:
+ * 	1. A local ID, which is stable for the lifetime of the session (which could be longer than that of the compressor object, as it may
+ * 		be serialized for offline usage). Available as soon as the stable ID is allocated. Local IDs are session-unique and are thus only
+ * 		publicly usable by the compressor that created the stable ID.
+ * 	2. A final ID, which is stable across serialization and deserialization of an IdCompressor. Available as soon as the range containing
+ * 		the corresponding local ID is totally ordered (via consensus) with respect to other sessions' allocations.
+ * 		Final IDs are known to and publicly usable by any compressor that has received them.
+ *
+ * Compressors will allocate UUIDs in non-random ways to reduce entropy allowing for optimized storage of the data needed
+ * to map the UUIDs to the numbers.
+ *
+ * A client may optionally supply an "override" for any generated ID, associating an arbitrary string with the local/final ID rather than
+ * the UUID that would otherwise be created.
+ *
+ * The following invariants are upheld by IdCompressor:
+ * 1. Local IDs will always decompress to the same UUIDs (or override string) for the lifetime of the session.
+ * 2. Final IDs will always decompress to the same UUIDs (or override string).
+ * 3. After a server-processed range of local IDs (from any session) is received by a compressor, any of those local IDs may be
+ * 		translated by the compressor into the corresponding final ID. For any given local ID, this translation will always yield the
+ * 		same final ID.
+ * 4. A UUID (or override string) will always compress into the same session-space ID for the lifetime of the session.
+ *
+ * Local IDs are sent across the wire in efficiently-represented ranges. These ranges are created by querying the compressor, and *must*
+ * be ordered (i.e. sent to the server) in the order they are created in order to preserve the above invariants.
+ *
+ * Session-local IDs can be used immediately after creation, but will eventually (after being sequenced) have a corresponding final ID. This
+ * could make reasoning about equality of those two forms (the local and final) difficult. For example, if a cache is keyed off of a
+ * local ID but is later queried using the final ID (which is semantically equal, as it decompresses to the same UUID/string) it will
+ * produce a cache miss. In order to make using collections of both remotely created and locally created IDs easy, regardless of whether the
+ * session-local IDs have been finalized, the compressor defines two "spaces" of IDs:
+ *
+ * 1. Session space: in this space, all IDs are normalized to their "most local form". This means that all IDs created by the local session
+ * will be in local form, regardless of if they have been finalized. Remotely created IDs, which could only have been received after
+ * finalizing and will never have a local form for the compressor, will of course be final IDs. This space should be used with consumer APIs
+ * and data structures, as the lifetime of the IDs is guaranteed to be the same as the compressor object. Care must be taken to not use
+ * these IDs across compressor objects, as the local IDs are specific to the compressor that created them.
+ *
+ * 2. Op space: in this space, all IDs are normalized to their "most final form". This means that all IDs except session-local IDs that
+ * have not yet been finalized will be in final ID form. This space is useful for serialization in ops (e.g. references), as other clients
+ * that receive them need not do any work to normalize them to *their* session-space in the common case. Note that IDs in op space may move
+ * out of Op space over time, namely, when a local ID in this space becomes finalized, and thereafter has a "more final form".
+ * Consequentially, it may be useful to restrict parameters of a persisted type to this space (to optimize perf), but it is potentially
+ * incorrect to use this type for a runtime variable. This is an asymmetry that does not affect session space, as local IDs are always as
+ * "local as possible".
+ *
+ * These two spaces naturally define a rule: consumers of compressed IDs should use session-space IDs, but serialized forms such as ops
+ * should use op-space IDs.
+ *
+ */
+class IdCompressor {
+    /**
+     * @param localSessionId the `IdCompressor`'s current local session ID.
+     * @param reservedIdCount the number of IDs that will be known by this compressor without relying on consensus. The reserved ID count
+     * for a given session must be constant for any compressor that contains IDs from that session (i.e. any DDS that uses the ID
+     * compressor must have the same reservedIdCount forever). Compressors with different reserved ID counts will fail to synchronize their
+     * IDs.
+     * @param attributionInfo information used by other clients to attribute IDs made by this client
+     */
+    constructor(localSessionId, reservedIdCount, attributionInfo) {
+        this.localSessionId = localSessionId;
+        this.reservedIdCount = reservedIdCount;
+        /**
+         * Trivially reach consensus on default cluster size and reserved IDs.
+         * These initial values must *NOT* change without careful consideration to compatibility.
+         */
+        this.newClusterCapacity = exports.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();
+        /**
+         * Boolean to track whether attribution has been sent with an ID range yet. Prevents unnecessary bloat of ranges.
+         */
+        this.sentAttributionInfo = false;
+        /**
+         * 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_1.AppendOnlySortedMap(compareFiniteNumbersReversed);
+        /**
+         * Maps local IDs to the cluster they belong to (if any). This can be used to efficiently convert a local ID to a
+         * final ID by finding an entry <= a given local ID (to find the cluster it is associated with) and checking
+         * it against `numFinalizedLocalIds`.
+         */
+        this.localIdToCluster = new AppendOnlySortedMap_1.AppendOnlyDoublySortedMap(compareFiniteNumbersReversed, (value) => value[0], IdCompressor.overrideComparator);
+        /**
+         * 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 sorted_btree_1.default(undefined, Common_1.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_1.AppendOnlySortedMap(Common_1.compareFiniteNumbers);
+        Common_1.assert(reservedIdCount >= 0, 'reservedIdCount must be non-negative');
+        this.localSession = this.createSession(localSessionId, attributionInfo);
+        if (reservedIdCount > 0) {
+            const clusterCapacity = this.clusterCapacity;
+            this.clusterCapacity = reservedIdCount;
+            const reservedIdRange = {
+                sessionId: reservedSessionId,
+                ids: {
+                    last: -reservedIdCount,
+                    overrides: [[-1, exports.legacySharedTreeInitialTreeId]],
+                },
+            };
+            // Reserved final IDs are implicitly finalized and no one locally created them, so finalizing immediately is safe.
+            this.finalizeCreationRange(reservedIdRange);
+            this.clusterCapacity = clusterCapacity;
+        }
+    }
+    /**
+     * 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) {
+        Common_1.assert(value > 0, 'Clusters must have a positive capacity');
+        Common_1.assert(value <= IdCompressor.maxClusterSize, 'Clusters must not exceed max cluster size');
+        this.newClusterCapacity = value;
+    }
+    /**
+     * Helper comparator for searching append-only sorted maps.
+     */
+    static overrideComparator(search, element) {
+        return Common_1.compareFiniteNumbers(search, element[0]);
+    }
+    /**
+     * 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, attributionInfo) {
+        const existingSession = this.sessions.get(sessionId);
+        if (existingSession !== undefined) {
+            Common_1.fail('createSession must only be called once for each session ID.');
+        }
+        const sessionUuid = NumericUuid_1.numericUuidFromStableId(sessionId);
+        Common_1.assert(!this.clustersAndOverridesInversion.has(sessionId));
+        const session = {
+            sessionUuid,
+            currentClusterDetails: undefined,
+            lastFinalizedLocalId: undefined,
+        };
+        Common_1.setPropertyIfDefined(attributionInfo, session, 'attributionInfo');
+        this.sessions.set(sessionId, session);
+        return session;
+    }
+    tryGetSession(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    /**
+     * Return the nth reserved ID.
+     * @param index the index of the ID to return
+     */
+    getReservedId(index) {
+        if (index < 0 || index >= this.reservedIdCount) {
+            Common_1.fail('Reserved Id index out of bounds');
+        }
+        // All reserved IDs are contiguous and finalized during the Compressor's construction, therefore they are always the lowest
+        // final IDs, beginning at 0
+        return index;
+    }
+    /**
+     * Returns an iterable of all IDs created by this compressor.
+     */
+    *getAllIdsFromLocalSession() {
+        // TODO: this will change when final IDs are returned eagerly
+        for (let i = 1; i <= this.localIdCount; i++) {
+            yield -i;
+        }
+    }
+    /**
+     * Returns the attribution info associated with the compressor that created the ID, if it exists.
+     */
+    attributeId(id) {
+        var _a;
+        const opSpaceNormalizedId = this.normalizeToOpSpace(id);
+        if (isLocalId(opSpaceNormalizedId)) {
+            return this.localSession.attributionInfo;
+        }
+        const [_, cluster] = (_a = this.getClusterForFinalId(opSpaceNormalizedId)) !== null && _a !== void 0 ? _a : Common_1.fail('Cluster does not exist for final ID');
+        return cluster.session.attributionInfo;
+    }
+    /**
+     * Provides the session-space IDs corresponding to a range of IDs.
+     * See `IdRange` for more details.
+     */
+    getIdsFromRange(rangeDescriptor, sessionId) {
+        var _a, _b, _c;
+        const { first, count } = rangeDescriptor;
+        if (sessionId === this.localSessionId) {
+            return {
+                length: count,
+                get: (index) => {
+                    if (index < 0 || index >= count) {
+                        Common_1.fail('Index out of bounds of range.');
+                    }
+                    return (first - index);
+                },
+            };
+        }
+        else {
+            const session = (_a = this.tryGetSession(sessionId)) !== null && _a !== void 0 ? _a : Common_1.fail('Unknown session, range may not be finalized.');
+            const firstNumericUuid = NumericUuid_1.incrementUuid(session.sessionUuid, -first - 1);
+            const firstFinal = (_b = this.compressNumericUuid(firstNumericUuid)) !== null && _b !== void 0 ? _b : Common_1.fail('Remote range must be finalized before getting IDs.');
+            Common_1.assert(isFinalId(firstFinal), 'ID from a remote session ID must have final form, as overrides are impossible by definition.');
+            const [baseFinalId, cluster] = (_c = this.getClusterForFinalId(firstFinal)) !== null && _c !== void 0 ? _c : Common_1.fail();
+            const numIdsRemainingInFirstCluster = cluster.capacity - (firstFinal - baseFinalId);
+            let pivotFinal;
+            if (count > numIdsRemainingInFirstCluster) {
+                const compressedPivot = this.compressNumericUuid(NumericUuid_1.incrementUuid(firstNumericUuid, numIdsRemainingInFirstCluster));
+                // Looking up the actual cluster can be avoided, as it is guaranteed that at most one new cluster will be
+                // created when finalizing a range (regardless of size) due to the expansion optimization.
+                if (compressedPivot === undefined || isLocalId(compressedPivot)) {
+                    Common_1.fail('ID from a remote session ID must have final form, as overrides are impossible by definition.');
+                }
+                else {
+                    pivotFinal = compressedPivot;
+                }
+            }
+            return {
+                length: count,
+                get: (index) => {
+                    if (index < 0 || index >= count) {
+                        Common_1.fail('Index out of bounds of range.');
+                    }
+                    if (index < numIdsRemainingInFirstCluster) {
+                        return (firstFinal + index);
+                    }
+                    else {
+                        return ((pivotFinal !== null && pivotFinal !== void 0 ? pivotFinal : Common_1.fail('Pivot must exist if range spans clusters.')) +
+                            (index - numIdsRemainingInFirstCluster));
+                    }
+                },
+            };
+        }
+    }
+    /**
+     * 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;
+        Common_1.assert(lastLocalInRange <= lastTakenNormalized);
+        let ids;
+        if (lastLocalInRange !== lastTakenNormalized) {
+            const firstLocalInRange = (lastTakenNormalized - 1);
+            const localOverrides = [
+                ...this.localOverrides.getRange((lastTakenNormalized - 1), lastLocalInRange),
+            ];
+            if (localOverrides.length > 0) {
+                // Cast: typecript 4.4.4 doesn't infer that `localOverrides` has at least one element and is therefore an `Overrides`
+                const overrides = localOverrides;
+                Common_1.assert(overrides[0][0] <= firstLocalInRange);
+                Common_1.assert(overrides[overrides.length - 1][0] >= lastLocalInRange);
+                ids = {
+                    overrides,
+                };
+                const first = firstLocalInRange === overrides[0][0] ? undefined : firstLocalInRange;
+                const last = lastLocalInRange === overrides[overrides.length - 1][0] ? undefined : lastLocalInRange;
+                Common_1.setPropertyIfDefined(first, ids, 'first');
+                Common_1.setPropertyIfDefined(last, ids, 'last');
+            }
+            else {
+                ids = {
+                    first: firstLocalInRange,
+                    last: lastLocalInRange,
+                };
+            }
+            this.lastTakenLocalId = lastLocalInRange;
+        }
+        const range = { sessionId: this.localSessionId };
+        if (!this.sentAttributionInfo) {
+            Common_1.setPropertyIfDefined(this.localSession.attributionInfo, range, 'attributionInfo');
+            this.sentAttributionInfo = true;
+        }
+        if (ids === undefined) {
+            return range;
+        }
+        Common_1.assert(this.lastTakenLocalId === -this.localIdCount && this.lastTakenLocalId !== lastTakenNormalized, '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;
+        const { sessionId, attributionInfo } = range;
+        const isLocal = sessionId === this.localSessionId;
+        let session = this.tryGetSession(sessionId);
+        Common_1.assert(range.attributionInfo === undefined || session === undefined || isLocal, 'Attribution info can only be supplied on initial range for a session, and never modified.');
+        session !== null && session !== void 0 ? session : (session = this.createSession(sessionId, attributionInfo));
+        const ids = IdRange_1.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 normalizedLastFinalized = (_a = session.lastFinalizedLocalId) !== null && _a !== void 0 ? _a : 0;
+        const { first: newFirstFinalizedLocalId, last: newLastFinalizedLocalId } = ids;
+        Common_1.assert(newFirstFinalizedLocalId === normalizedLastFinalized - 1, 'Ranges finalized out of order.');
+        // The total number of session-local IDs to finalize
+        const finalizeCount = normalizedLastFinalized - newLastFinalizedLocalId;
+        Common_1.assert(finalizeCount >= 1, 'Cannot finalize an empty range.');
+        let initialClusterCount = 0;
+        let remainingCount = finalizeCount;
+        let newBaseUuid;
+        if (currentCluster !== undefined && currentBaseFinalId !== undefined) {
+            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;
+                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;
+                    currentCluster.capacity += expansionAmount;
+                    this.nextClusterBaseFinalId = (this.nextClusterBaseFinalId + expansionAmount);
+                    Common_1.assert(this.nextClusterBaseFinalId < Number.MAX_SAFE_INTEGER, 'The number of allocated final IDs must not exceed the JS maximum safe integer.');
+                    this.checkClusterForCollision(currentCluster);
+                }
+            }
+            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 = NumericUuid_1.incrementUuid(currentCluster.baseUuid, currentCluster.capacity);
+                currentCluster.count += remainingCapacity;
+                remainingCount -= remainingCapacity;
+            }
+        }
+        else {
+            // Session has never made a cluster, form a new one with the session UUID as the baseUuid
+            newBaseUuid = session.sessionUuid;
+        }
+        // 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) {
+                Common_1.fail('Should not create an empty cluster.');
+            }
+            if (currentCluster !== undefined && currentCluster.capacity !== currentCluster.count) {
+                Common_1.fail('Cluster must be filled before another is allocated.');
+            }
+            newBaseFinalId = this.nextClusterBaseFinalId;
+            newCluster = {
+                baseUuid: newBaseUuid,
+                capacity: Math.max(this.newClusterCapacity, remainingCount),
+                count: remainingCount,
+                session,
+            };
+            const usedCapacity = finalizeCount - remainingCount;
+            localIdPivot = (newFirstFinalizedLocalId - usedCapacity);
+            if (isLocal) {
+                this.localIdToCluster.append(localIdPivot, [newBaseFinalId, newCluster]);
+            }
+            this.checkClusterForCollision(newCluster);
+            this.clustersAndOverridesInversion.set(NumericUuid_1.stableIdFromNumericUuid(newCluster.baseUuid), {
+                clusterBase: newBaseFinalId,
+                cluster: newCluster,
+            });
+            session.currentClusterDetails = { cluster: newCluster, clusterBase: newBaseFinalId };
+            this.nextClusterBaseFinalId = (this.nextClusterBaseFinalId + newCluster.capacity);
+            Common_1.assert(this.nextClusterBaseFinalId < Number.MAX_SAFE_INTEGER, '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
+                Common_1.assert(i === 0 || overriddenLocal < overrides[i - 1][0], 'Override IDs must be in sorted order.');
+                Common_1.assert(overriddenLocal < normalizedLastFinalized, 'Ranges finalized out of order.');
+                Common_1.assert(overriddenLocal >= newLastFinalizedLocalId, '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.
+                    Common_1.assert(newCluster !== undefined && newBaseFinalId !== undefined, 'No cluster was created when overflow occurred.');
+                    cluster = newCluster;
+                    overriddenFinal = (newBaseFinalId + (localIdPivot - overriddenLocal));
+                }
+                else {
+                    // Override was finalized into an existing cluster
+                    Common_1.assert(currentCluster !== undefined && currentBaseFinalId !== undefined, 'No cluster exists but IDs were finalized.');
+                    cluster = currentCluster;
+                    overriddenFinal = (currentBaseFinalId +
+                        initialClusterCount +
+                        (normalizedLastFinalized - overriddenLocal) -
+                        1);
+                }
+                (_b = cluster.overrides) !== null && _b !== void 0 ? _b : (cluster.overrides = new Map());
+                const inversionKey = IdCompressor.createInversionKey(override);
+                // TODO: This cast can be removed on typescript 4.6
+                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 {
+                        Common_1.assert(!isLocal || mostFinalExistingOverride === overriddenLocal, '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;
+                }
+                Common_1.assert(!cluster.overrides.has(overriddenFinal), '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,
+                    };
+                    Common_1.setPropertyIfDefined(associatedLocal, unifiedOverride, 'associatedLocalId');
+                    cluster.overrides.set(overriddenFinal, unifiedOverride);
+                }
+                const finalizedOverride = {
+                    cluster,
+                    originalOverridingFinal: overriddenFinal,
+                };
+                Common_1.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);
+                }
+            }
+        }
+        session.lastFinalizedLocalId = newLastFinalizedLocalId;
+    }
+    checkClusterForCollision(cluster) {
+        const maxClusterUuid = NumericUuid_1.incrementUuid(cluster.baseUuid, cluster.capacity - 1);
+        const maxClusterStableId = NumericUuid_1.stableIdFromNumericUuid(maxClusterUuid);
+        const closestMatch = this.clustersAndOverridesInversion.getPairOrNextLower(maxClusterStableId);
+        if (closestMatch !== undefined) {
+            const [inversionKey, compressionMapping] = closestMatch;
+            if (!IdCompressor.isClusterInfo(compressionMapping)) {
+                if (NumericUuid_1.isStableId(inversionKey) &&
+                    IdCompressor.uuidsMightCollide(inversionKey, maxClusterStableId, cluster.capacity)) {
+                    const numericOverride = NumericUuid_1.numericUuidFromStableId(inversionKey);
+                    const delta = NumericUuid_1.getPositiveDelta(maxClusterUuid, numericOverride, cluster.capacity - 1);
+                    if (delta !== undefined) {
+                        IdCompressor.failWithCollidingOverride(inversionKey);
+                    }
+                }
+            }
+        }
+    }
+    static failWithCollidingOverride(override) {
+        Common_1.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) {
+        // TODO: This cast can be removed on typescript 4.6
+        return NumericUuid_1.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 = NumericUuid_1.numericUuidFromStableId(stableOverride);
+                    const delta = NumericUuid_1.getPositiveDelta(numericOverride, cluster.baseUuid, cluster.capacity - 1);
+                    if (delta !== undefined) {
+                        if (isFinalOverride) {
+                            IdCompressor.failWithCollidingOverride(inversionKey);
+                        }
+                        else {
+                            if (delta < cluster.count) {
+                                return this.normalizeToSessionSpace((compressionMapping.clusterBase + delta));
+                            }
+                            else {
+                                IdCompressor.failWithCollidingOverride(inversionKey);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        const override = (_a = numericOverride !== null && numericOverride !== void 0 ? numericOverride : stableOverride) !== null && _a !== void 0 ? _a : (IdCompressor.isStableInversionKey(inversionKey) ? inversionKey : undefined);
+        if (override !== undefined) {
+            const localId = this.getLocalIdForStableId(override);
+            if (localId !== undefined) {
+                return localId;
+            }
+        }
+        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) {
+        // If any ID exists for this override (locally or remotely allocated), return it (after ensuring it is in session-space).
+        if (override !== undefined) {
+            const inversionKey = IdCompressor.createInversionKey(override);
+            const existingIds = this.getExistingIdsForNewOverride(inversionKey, false);
+            if (existingIds !== undefined) {
+                return typeof existingIds === 'number' ? existingIds : existingIds[0];
+            }
+            else {
+                const newLocalId = this.generateNextLocalId();
+                this.localOverrides.append(newLocalId, override);
+                // Since the local ID was just created, it is in both session and op space
+                const compressionMapping = newLocalId;
+                this.clustersAndOverridesInversion.set(inversionKey, compressionMapping);
+                return newLocalId;
+            }
+        }
+        else {
+            return this.generateNextLocalId();
+        }
+    }
+    /**
+     * Generates a range of compressed IDs.
+     * This should ONLY be called to generate IDs for local operations.
+     * @param count the number of IDs to generate, must be > 0.
+     * @returns a persistable descriptor of the ID range.
+     */
+    generateCompressedIdRange(count) {
+        Common_1.assert(count > 0, 'Must generate a nonzero number of IDs.');
+        Common_1.assert(count <= Number.MAX_SAFE_INTEGER, 'The number of allocated local IDs must not exceed the JS maximum safe integer.');
+        const first = this.generateNextLocalId();
+        this.localIdCount += count - 1;
+        return { first, count };
+    }
+    generateNextLocalId() {
+        return -++this.localIdCount;
+    }
+    /**
+     * 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 : Common_1.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) {
+                return undefined;
+            }
+            else {
+                const [baseFinalId, cluster] = possibleCluster;
+                const override = IdCompressor.tryGetOverride(cluster, id);
+                if (override !== undefined) {
+                    return override;
+                }
+                else {
+                    const offsetInCluster = id - baseFinalId;
+                    return NumericUuid_1.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);
+            if (localOverride !== undefined) {
+                return localOverride;
+            }
+            else {
+                return NumericUuid_1.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 : Common_1.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;
+        // TODO: This cast can be removed on typescript 4.6, and should give improved typesafety.
+        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) {
+                    if (IdCompressor.isUnfinalizedOverride(compressionMapping)) {
+                        return compressionMapping;
+                    }
+                    else {
+                        const cluster = compressionMapping.cluster;
+                        Common_1.assert(IdCompressor.tryGetOverride(cluster, compressionMapping.originalOverridingFinal) !==
+                            undefined, 'No override for cluster marked as having one.');
+                        return ((_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 = NumericUuid_1.numericUuidFromStableId(inversionKey));
+                const uuidOffset = NumericUuid_1.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
+            // TODO: This cast can be removed on typescript 4.6
+            const localId = this.getLocalIdForStableId(numericUuid !== null && numericUuid !== void 0 ? numericUuid : inversionKey);
+            if (localId !== undefined) {
+                return localId;
+            }
+        }
+        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;
+        if (isFinalId(id)) {
+            return id;
+        }
+        // Check if this local ID has not been allocated yet
+        if (-id > this.localIdCount) {
+            Common_1.fail('Supplied local ID was not created by this compressor.');
+        }
+        // Check if this local ID has not been finalized yet
+        const { lastFinalizedLocalId } = this.localSession;
+        if (lastFinalizedLocalId === undefined || id < lastFinalizedLocalId) {
+            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 : Common_1.fail('Bimap is malformed.');
+                if (!IdCompressor.isClusterInfo(compressionMapping) &&
+                    !IdCompressor.isUnfinalizedOverride(compressionMapping) &&
+                    compressionMapping.associatedLocalId === id) {
+                    return compressionMapping.originalOverridingFinal;
+                }
+            }
+            return id;
+        }
+        const [localBase, [finalBase, cluster]] = (_b = this.localIdToCluster.getPairOrNextLower(id)) !== null && _b !== void 0 ? _b : Common_1.fail('Locally created cluster should be added to the map when allocated');
+        const correspondingFinal = (finalBase + (localBase - id));
+        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, originSessionId) {
+        var _a, _b, _c;
+        const isLocalSession = originSessionId === this.localSessionId;
+        if (isLocalId(id)) {
+            if (isLocalSession) {
+                const localIndex = -id;
+                if (localIndex > this.localIdCount) {
+                    Common_1.fail('Supplied local ID was not created by this compressor.');
+                }
+                return id;
+            }
+            else {
+                const session = this.tryGetSession(originSessionId !== null && originSessionId !== void 0 ? originSessionId : Common_1.fail());
+                if (session === undefined) {
+                    Common_1.fail('No IDs have ever been finalized by the supplied session.');
+                }
+                const localCount = -id;
+                const numericUuid = NumericUuid_1.incrementUuid(session.sessionUuid, localCount - 1);
+                return (_a = this.compressNumericUuid(numericUuid)) !== null && _a !== void 0 ? _a : Common_1.fail('ID is not known to this compressor.');
+            }
+        }
+        const closestResult = this.localIdToCluster.getPairOrNextLowerByValue(id);
+        if (closestResult !== undefined) {
+            const [localBase, [finalBase, cluster]] = closestResult;
+            const indexInCluster = id - finalBase;
+            if (indexInCluster < cluster.count) {
+                return (localBase - indexInCluster);
+            }
+        }
+        // Check for a unified override finalized first by another session but to which the local session
+        // still has an associated local ID.
+        const [_, cluster] = (_b = this.getClusterForFinalId(id)) !== null && _b !== void 0 ? _b : Common_1.fail('Supplied final ID was not finalized by this compressor.');
+        const override = (_c = cluster.overrides) === null || _c === void 0 ? void 0 : _c.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 = NumericUuid_1.stableIdFromNumericUuid(numericUuid);
+        const sessionSpaceId = this.recompressInternal(stableId, numericUuid);
+        if (sessionSpaceId === undefined) {
+            return undefined;
+        }
+        return sessionSpaceId;
+    }
+    getLocalIdForStableId(stableId) {
+        // TODO: This cast can be removed on typescript 4.6
+        const numericUuid = (typeof stableId === 'string' ? NumericUuid_1.numericUuidFromStableId(stableId) : stableId);
+        const offset = NumericUuid_1.getPositiveDelta(numericUuid, this.localSession.sessionUuid, this.localIdCount - 1);
+        if (offset === undefined) {
+            return undefined;
+        }
+        return (-offset - 1);
+    }
+    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.
+     * @testOnly
+     */
+    equals(other, compareLocalState) {
+        if (compareLocalState) {
+            if (this.localIdCount !== other.localIdCount ||
+                this.localSessionId !== other.localSessionId ||
+                this.lastTakenLocalId !== other.lastTakenLocalId ||
+                this.sentAttributionInfo !== other.sentAttributionInfo) {
+                return false;
+            }
+            if (!this.localOverrides.equals(other.localOverrides, (a, b) => a === b)) {
+                return false;
+            }
+            if (!Common_1.compareMaps(this.sessions, other.sessions, (a, b) => IdCompressor.sessionDataEqual(a, b, true, 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 (a.attributionInfo !== b.attributionInfo ||
+            !NumericUuid_1.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) {
+        const areEqual = NumericUuid_1.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 ||
+                Common_1.compareMaps(Common_1.assertNotUndefined(a.overrides), Common_1.assertNotUndefined(b.overrides), (a, b) => {
+                    if (compareLocalState) {
+                        if (typeof a === 'string' || typeof b === 'string') {
+                            return a === b;
+                        }
+                        const overridesEqual = a.override === b.override &&
+                            a.originalOverridingFinal === b.originalOverridingFinal &&
+                            (!compareLocalState || a.associatedLocalId === b.associatedLocalId);
+                        return overridesEqual;
+                    }
+                    const uuidA = typeof a === 'string' ? a : a.override;
+                    const uuidB = typeof b === 'string' ? b : b.override;
+                    if (typeof a !== 'string' &&
+                        typeof b !== 'string' &&
+                        a.originalOverridingFinal !== b.originalOverridingFinal) {
+                        return false;
+                    }
+                    return uuidA === uuidB;
+                }));
+        return areEqual;
+    }
+    serialize(withSession) {
+        var _a;
+        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];
+                if (session.attributionInfo !== undefined) {
+                    sessionData.push(session.attributionInfo);
+                }
+                sessionIdToSessionIndex.set(sessionId, serializedSessions.length);
+                serializedSessions.push(sessionData);
+            }
+        }
+        const serializedClusters = [];
+        for (const [baseFinalId, cluster] of this.finalIdToCluster.entries()) {
+            const sessionId = NumericUuid_1.stableIdFromNumericUuid(cluster.session.sessionUuid);
+            if (sessionId !== reservedSessionId) {
+                const sessionIndex = (_a = sessionIdToSessionIndex.get(sessionId)) !== null && _a !== void 0 ? _a : Common_1.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
+        Common_1.assert(serializedSessions.length - this.sessions.size <= 2, 'session not serialized');
+        const serializedIdCompressor = {
+            version: currentWrittenVersion,
+            reservedIdCount: this.reservedIdCount,
+            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,
+                    sentAttributionInfo: this.sentAttributionInfo,
+                };
+            }
+            return serializedWithSession;
+        }
+        return serializedIdCompressor;
+    }
+    static deserialize(serialized, newSessionIdMaybe, attributionInfoMaybe) {
+        const hasSession = hasOngoingSession(serialized);
+        let localSessionId;
+        let attributionInfo;
+        let serializedLocalState;
+        if (hasSession) {
+            Common_1.assert(newSessionIdMaybe === undefined && attributionInfoMaybe === undefined);
+            // TODO: This cast can be removed on typescript 4.6
+            [localSessionId, attributionInfo] =
+                serialized.sessions[serialized.localSessionIndex];
+            // TODO: This cast can be removed on typescript 4.6
+            serializedLocalState = serialized.localState;
+        }
+        else {
+            Common_1.assert(newSessionIdMaybe !== undefined);
+            localSessionId = newSessionIdMaybe;
+            attributionInfo = attributionInfoMaybe;
+        }
+        const { clusterCapacity, reservedIdCount, sessions: serializedSessions, clusters: serializedClusters, } = serialized;
+        const compressor = new IdCompressor(localSessionId, reservedIdCount, attributionInfo);
+        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;
+            compressor.sentAttributionInfo = serializedLocalState.sentAttributionInfo;
+            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, attributionInfo] = serializedSession;
+            if (sessionId === localSessionId) {
+                Common_1.assert(hasSession, 'Cannot resume existing session.');
+                sessionInfos.push({ session: compressor.localSession, sessionId });
+            }
+            else {
+                const session = compressor.createSession(sessionId, attributionInfo);
+                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: NumericUuid_1.incrementUuid(sessionUuid, currentIdCount),
+                session,
+            };
+            const lastFinalizedNormalized = lastFinalizedLocalId !== null && lastFinalizedLocalId !== void 0 ? lastFinalizedLocalId : 0;
+            const clusterBase = compressor.nextClusterBaseFinalId;
+            if (serializedLocalState !== undefined && sessionId === compressor.localSessionId) {
+                compressor.localIdToCluster.append((lastFinalizedNormalized - 1), [
+                    clusterBase,
+                    cluster,
+                ]);
+            }
+            session.lastFinalizedLocalId = (lastFinalizedNormalized - count);
+            session.currentClusterDetails = { clusterBase, cluster };
+            compressor.nextClusterBaseFinalId = (compressor.nextClusterBaseFinalId + capacity);
+            compressor.finalIdToCluster.append(clusterBase, cluster);
+            compressor.clustersAndOverridesInversion.set(NumericUuid_1.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) {
+                            Common_1.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) {
+                            Common_1.setPropertyIfDefined(associatedLocal, finalizedOverride, 'associatedLocalId');
+                        }
+                        compressor.clustersAndOverridesInversion.set(IdCompressor.createInversionKey(override), finalizedOverride);
+                    }
+                }
+            }
+        }
+        Common_1.assert(compressor.localSession.lastFinalizedLocalId === undefined ||
+            compressor.localIdCount >= -compressor.localSession.lastFinalizedLocalId);
+        return compressor;
+    }
+    static convertToCurrentVersion(serializedCompressor, hasSession) {
+        if (serializedCompressor.version !== currentWrittenVersion) {
+            Common_1.fail('Unknown SerializedIdCompressor version number');
+        }
+        const serialized = serializedCompressor;
+        if (hasSession !== hasOngoingSession(serialized)) {
+            return undefined;
+        }
+        return serialized;
+    }
+}
+exports.IdCompressor = IdCompressor;
+/**
+ * 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.
+ */
+function hasOngoingSession(serialized) {
+    return serialized.localSessionIndex !== undefined;
+}
+exports.hasOngoingSession = hasOngoingSession;
+function deserializeCluster(serializedCluster) {
+    const [sessionIndex, capacity, countOrOverrides, overrides] = serializedCluster;
+    const hasCount = typeof countOrOverrides === 'number';
+    return {
+        sessionIndex,
+        capacity,
+        // TODO: This cast can be removed on typescript 4.6
+        count: (hasCount ? countOrOverrides : capacity),
+        // TODO: This cast can be removed on typescript 4.6
+        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 = [];
+/**
+ * A numeric comparator used for sorting in descending order.
+ */
+function compareFiniteNumbersReversed(a, b) {
+    return b - a;
+}
+//# sourceMappingURL=IdCompressor.js.map