@fluidframework/id-compressor 2.0.0-internal.8.0.1 → 2.0.0-rc.1.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @fluidframework/id-compressor
 
+## 2.0.0-rc.1.0.0
+
+### Minor Changes
+
+-   id-compressor: Cluster allocation strategy updated ([#19066](https://github.com/microsoft/FluidFramework/issues/19066)) [0c36eb5f53](https://github.com/microsoft/FluidFramework/commits/0c36eb5f539362a8e27982e831a3ffe7999c1478)
+
+    This change adjusts the cluster allocation strategy for ghost sessions to exactly fill the cluster instead of needlessly allocating a large cluster.
+    It will also not make a cluster at all if IDs are not allocated.
+    This change adjusts a computation performed at a consensus point, and thus breaks any sessions collaborating across version numbers.
+    The version for the serialized format has been bumped to 2.0, and 1.0 documents will fail to load with the following error:
+    IdCompressor version 1.0 is no longer supported.
+
 ## 2.0.0-internal.8.0.0
 
 Dependency updates only.

package/README.md

@@ -30,12 +30,6 @@ When taking a dependency on a Fluid Framework library, we recommend using a `^`
 While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries,
 library consumers should always prefer `^`.
 
-Note that when depending on a library version of the form `2.0.0-internal.x.y.z`, called the Fluid internal version scheme,
-you must use a `>= <` dependency range (such as `>=2.0.0-internal.x.y.z <2.0.0-internal.w.0.0` where `w` is `x+1`).
-Standard `^` and `~` ranges will not work as expected.
-See the [@fluid-tools/version-tools](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/version-tools/README.md)
-package for more information including tools to convert between version schemes.
-
 <!-- prettier-ignore-end -->
 
 <!-- AUTO-GENERATED-CONTENT:END -->

package/api-extractor-esm.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-base-esm.json"
+}

package/api-extractor-lint.json

@@ -1,13 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-lint.json",
-	"messages": {
-		"extractorMessageReporting": {
-			// TODO: remove once base config has this enabled as an error
-			"ae-incompatible-release-tags": {
-				"logLevel": "error",
-				"addToApiReportFile": false
-			}
-		}
-	}
+	"extends": "../../../common/build/build-common/api-extractor-lint.json"
 }

package/api-extractor.json

@@ -1,12 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.json",
-	"messages": {
-		"extractorMessageReporting": {
-			// TODO: Add missing documentation and remove this rule override
-			"ae-undocumented": {
-				"logLevel": "none"
-			}
-		}
-	}
+	"extends": "../../../common/build/build-common/api-extractor-base.json"
 }

package/api-report/id-compressor.api.md

@@ -29,6 +29,7 @@ export function generateStableId(): StableId;
 
 // @alpha @deprecated
 export class IdCompressor implements IIdCompressor, IIdCompressorCore {
+    beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): void;
     // @deprecated (undocumented)
     static create(logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
     // @deprecated (undocumented)
@@ -76,7 +77,7 @@ export interface IdCreationRange {
     readonly sessionId: SessionId;
 }
 
-// @alpha
+// @public
 export interface IIdCompressor {
     decompress(id: SessionSpaceCompressedId): StableId;
     generateCompressedId(): SessionSpaceCompressedId;
@@ -90,6 +91,7 @@ export interface IIdCompressor {
 
 // @alpha (undocumented)
 export interface IIdCompressorCore {
+    beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): any;
     finalizeCreationRange(range: IdCreationRange): void;
     serialize(withSession: true): SerializedIdCompressorWithOngoingSession;
     serialize(withSession: false): SerializedIdCompressorWithNoSession;
@@ -99,7 +101,7 @@ export interface IIdCompressorCore {
 // @internal
 export function isStableId(str: string): str is StableId;
 
-// @alpha
+// @public
 export type OpSpaceCompressedId = number & {
     readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
 };
@@ -119,17 +121,17 @@ export type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor &
     readonly _hasLocalState: "1281acae-6d14-47e7-bc92-71c8ee0819cb";
 };
 
-// @alpha
+// @public
 export type SessionId = StableId & {
     readonly SessionId: "4498f850-e14e-4be9-8db0-89ec00997e58";
 };
 
-// @alpha
+// @public
 export type SessionSpaceCompressedId = number & {
     readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e";
 };
 
-// @alpha
+// @public
 export type StableId = string & {
     readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a";
 };

package/dist/id-compressor-alpha.d.ts

@@ -65,6 +65,7 @@ export declare class IdCompressor implements IIdCompressor, IIdCompressorCore {
     private nextRequestedClusterSize;
     private telemetryLocalIdCount;
     private telemetryEagerFinalIdCount;
+    private ongoingGhostSession?;
     private constructor();
     /**
      * @deprecated Use `createIdCompressor` instead.
@@ -75,6 +76,10 @@ export declare class IdCompressor implements IIdCompressor, IIdCompressorCore {
      */
     static create(sessionId: SessionId, logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
     generateCompressedId(): SessionSpaceCompressedId;
+    /**
+     * {@inheritdoc IIdCompressorCore.beginGhostSession}
+     */
+    beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): void;
     private generateNextLocalId;
     takeNextCreationRange(): IdCreationRange;
     private static assertValidRange;
@@ -89,6 +94,7 @@ export declare class IdCompressor implements IIdCompressor, IIdCompressorCore {
     serialize(withSession: false): SerializedIdCompressorWithNoSession;
     static deserialize(serialized: SerializedIdCompressorWithOngoingSession): IdCompressor;
     static deserialize(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId): IdCompressor;
+    private static deserialize2_0;
     equals(other: IdCompressor, includeLocalState: boolean): boolean;
 }
 
@@ -178,7 +184,7 @@ export declare interface IdCreationRange {
  *
  * 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.
- * @alpha
+ * @public
  */
 export declare interface IIdCompressor {
     localSessionId: SessionId;
@@ -240,6 +246,27 @@ export declare interface IIdCompressorCore {
      * @param range - the range of session-local IDs to finalize.
      */
     finalizeCreationRange(range: IdCreationRange): void;
+    /**
+     * Run a callback that is performed from the perspective of a special "ghost" session.
+     * Any ids generated by this session will be immediately finalized on the local client as if
+     * they were created by a remote client with `ghostSessionId`.
+     *
+     * *WARNING:* This API requires an external consensus mechanism to safely use:
+     * In an attached container (i.e. multiple clients may have the document loaded), all clients must guarantee that:
+     * - They invoke this API starting from the same finalized creation ranges
+     * - This API is invoked with the same ghost session id
+     * - `ghostSessionCallback` deterministically mints the same number of ids on each client within the ghost session
+     * Failure to meet these requirement will result in divergence across clients and eventual consistency errors.
+     * While the ghost sesion callback is running, IdCompressor does not support serialization.
+     * @remarks This API is primarily intended for data migration scenarios which are able to deterministically transform
+     * data in some format into data in a new format.
+     * The first requirement (that all clients must invoke the API with the same finalized creation ranges) is guaranteed
+     * for this scenario because the data transformation callback occurs at a specific ack within the op stream on all
+     * clients, and clients don't finalize creation ranges for local changes they might have at this point in time.
+     * @param ghostSessionId - The session id that minted ids generated within `ghostSessionCallback` should be attributed to.
+     * @param ghostSessionCallback - Callback which mints ids attributed to the ghost session.
+     */
+    beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): any;
     /**
      * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `IdCompressor.deserialize()`.
      * This includes finalized state as well as un-finalized state and is therefore suitable for use in offline scenarios.
@@ -258,7 +285,7 @@ export declare interface IIdCompressorCore {
  * A compressed ID that has been normalized into "op space".
  * Serialized/persisted structures (e.g. ops) should use op-space IDs as a performance optimization, as they require less normalizing when
  * received by a remote client due to the fact that op space for a given compressor is session space for all other compressors.
- * @alpha
+ * @public
  */
 export declare type OpSpaceCompressedId = number & {
     readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
@@ -290,7 +317,7 @@ export declare type SerializedIdCompressorWithOngoingSession = SerializedIdCompr
 
 /**
  * A StableId which is suitable for use as a session identifier
- * @alpha
+ * @public
  */
 export declare type SessionId = StableId & {
     readonly SessionId: "4498f850-e14e-4be9-8db0-89ec00997e58";
@@ -300,7 +327,7 @@ export declare type SessionId = StableId & {
  * A compressed ID that has been normalized into "session space" (see `IdCompressor` for more).
  * Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to
  * the scope of the session (i.e. compressor) that produced them.
- * @alpha
+ * @public
  */
 export declare type SessionSpaceCompressedId = number & {
     readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e";
@@ -311,7 +338,7 @@ export declare type SessionSpaceCompressedId = number & {
  * A 128-bit Universally Unique IDentifier. Represented here
  * with a string of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
  * where x is a lowercase hex digit.
- * @alpha
+ * @public
  */
 export declare type StableId = string & {
     readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a";

package/dist/id-compressor-beta.d.ts

@@ -14,15 +14,125 @@ import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
 
 /* Excluded from this release type: IdCreationRange */
 
-/* Excluded from this release type: IIdCompressor */
+/**
+ * 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 session-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. These IDs are session-unique and are thus only
+ * safely usable within the scope of the compressor that created it.
+ *
+ * 2. A final ID, which is stable across serialization and deserialization of an IdCompressor. Available as soon as the range containing
+ * the corresponding session-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.
+ *
+ * The following invariants are upheld by IdCompressor:
+ *
+ * 1. Session-local IDs will always decompress to the same UUIDs for the lifetime of the session.
+ *
+ * 2. Final IDs will always decompress to the same UUIDs.
+ *
+ * 3. After a server-processed range of session-local IDs (from any session) is received by a compressor, any of those session-local IDs may be
+ * translated by the compressor into the corresponding final ID. For any given session-local ID, this translation will always yield the
+ * same final ID.
+ *
+ * 4. A UUID will always compress into the same session-local ID for the lifetime of the session.
+ *
+ * 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 difficult. For example, if a cache is keyed off of a
+ * session-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 session-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.
+ * @public
+ */
+export declare interface IIdCompressor {
+    localSessionId: SessionId;
+    /**
+     * Generates a new compressed ID or returns an existing one.
+     * This should ONLY be called to generate IDs for local operations.
+     * @returns A new local ID in session space.
+     */
+    generateCompressedId(): SessionSpaceCompressedId;
+    /**
+     * Normalizes a session space ID into op space.
+     * @param id - the local ID to normalize.
+     * @returns the ID in op space.
+     */
+    normalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;
+    /**
+     * Normalizes an ID into session space.
+     * @param id - the ID to normalize. If it is a local ID, it is assumed to have been created by the session corresponding
+     * to `sessionId`.
+     * @param originSessionId - the session from which `id` originated
+     * @returns the session-space ID corresponding to `id`, which might not have been a final ID if the client that created it had not yet
+     * finalized it. This can occur when a client references an ID during the window of time in which it is waiting to receive the ordered
+     * range that contained it from the server.
+     */
+    normalizeToSessionSpace(id: OpSpaceCompressedId, originSessionId: SessionId): SessionSpaceCompressedId;
+    /**
+     * Decompresses a previously compressed ID into a UUID.
+     * @param id - the compressed ID to be decompressed.
+     * @returns the UUID associated with the compressed ID. Fails if the ID was not generated by this compressor.
+     */
+    decompress(id: SessionSpaceCompressedId): StableId;
+    /**
+     * Recompresses a UUID.
+     * @param uncompressed - the UUID to recompress.
+     * @returns the `CompressedId` associated with `uncompressed`. Fails if it has not been previously compressed by this compressor.
+     */
+    recompress(uncompressed: StableId): SessionSpaceCompressedId;
+    /**
+     * Attempts to recompresses a UUID.
+     * @param uncompressed - the UUID to recompress,
+     * @returns the `CompressedId` associated with `uncompressed` or undefined if it has not been previously compressed by this compressor.
+     */
+    tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
+}
 
 /* Excluded from this release type: IIdCompressorCore */
 
 /* Excluded from this release type: isStableId */
 
-/* Excluded from this release type: ITelemetryBaseLogger */
-
-/* Excluded from this release type: OpSpaceCompressedId */
+/**
+ * A compressed ID that has been normalized into "op space".
+ * Serialized/persisted structures (e.g. ops) should use op-space IDs as a performance optimization, as they require less normalizing when
+ * received by a remote client due to the fact that op space for a given compressor is session space for all other compressors.
+ * @public
+ */
+export declare type OpSpaceCompressedId = number & {
+    readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
+};
 
 /* Excluded from this release type: SerializedIdCompressor */
 
@@ -30,10 +140,33 @@ import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
 
 /* Excluded from this release type: SerializedIdCompressorWithOngoingSession */
 
-/* Excluded from this release type: SessionId */
-
-/* Excluded from this release type: SessionSpaceCompressedId */
-
-/* Excluded from this release type: StableId */
+/**
+ * A StableId which is suitable for use as a session identifier
+ * @public
+ */
+export declare type SessionId = StableId & {
+    readonly SessionId: "4498f850-e14e-4be9-8db0-89ec00997e58";
+};
+
+/**
+ * A compressed ID that has been normalized into "session space" (see `IdCompressor` for more).
+ * Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to
+ * the scope of the session (i.e. compressor) that produced them.
+ * @public
+ */
+export declare type SessionSpaceCompressedId = number & {
+    readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e";
+};
+
+/**
+ * A version 4, variant 1 uuid (https://datatracker.ietf.org/doc/html/rfc4122).
+ * A 128-bit Universally Unique IDentifier. Represented here
+ * with a string of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
+ * where x is a lowercase hex digit.
+ * @public
+ */
+export declare type StableId = string & {
+    readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a";
+};
 
 export { }

package/dist/id-compressor-public.d.ts

@@ -14,15 +14,125 @@ import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
 
 /* Excluded from this release type: IdCreationRange */
 
-/* Excluded from this release type: IIdCompressor */
+/**
+ * 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 session-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. These IDs are session-unique and are thus only
+ * safely usable within the scope of the compressor that created it.
+ *
+ * 2. A final ID, which is stable across serialization and deserialization of an IdCompressor. Available as soon as the range containing
+ * the corresponding session-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.
+ *
+ * The following invariants are upheld by IdCompressor:
+ *
+ * 1. Session-local IDs will always decompress to the same UUIDs for the lifetime of the session.
+ *
+ * 2. Final IDs will always decompress to the same UUIDs.
+ *
+ * 3. After a server-processed range of session-local IDs (from any session) is received by a compressor, any of those session-local IDs may be
+ * translated by the compressor into the corresponding final ID. For any given session-local ID, this translation will always yield the
+ * same final ID.
+ *
+ * 4. A UUID will always compress into the same session-local ID for the lifetime of the session.
+ *
+ * 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 difficult. For example, if a cache is keyed off of a
+ * session-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 session-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.
+ * @public
+ */
+export declare interface IIdCompressor {
+    localSessionId: SessionId;
+    /**
+     * Generates a new compressed ID or returns an existing one.
+     * This should ONLY be called to generate IDs for local operations.
+     * @returns A new local ID in session space.
+     */
+    generateCompressedId(): SessionSpaceCompressedId;
+    /**
+     * Normalizes a session space ID into op space.
+     * @param id - the local ID to normalize.
+     * @returns the ID in op space.
+     */
+    normalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;
+    /**
+     * Normalizes an ID into session space.
+     * @param id - the ID to normalize. If it is a local ID, it is assumed to have been created by the session corresponding
+     * to `sessionId`.
+     * @param originSessionId - the session from which `id` originated
+     * @returns the session-space ID corresponding to `id`, which might not have been a final ID if the client that created it had not yet
+     * finalized it. This can occur when a client references an ID during the window of time in which it is waiting to receive the ordered
+     * range that contained it from the server.
+     */
+    normalizeToSessionSpace(id: OpSpaceCompressedId, originSessionId: SessionId): SessionSpaceCompressedId;
+    /**
+     * Decompresses a previously compressed ID into a UUID.
+     * @param id - the compressed ID to be decompressed.
+     * @returns the UUID associated with the compressed ID. Fails if the ID was not generated by this compressor.
+     */
+    decompress(id: SessionSpaceCompressedId): StableId;
+    /**
+     * Recompresses a UUID.
+     * @param uncompressed - the UUID to recompress.
+     * @returns the `CompressedId` associated with `uncompressed`. Fails if it has not been previously compressed by this compressor.
+     */
+    recompress(uncompressed: StableId): SessionSpaceCompressedId;
+    /**
+     * Attempts to recompresses a UUID.
+     * @param uncompressed - the UUID to recompress,
+     * @returns the `CompressedId` associated with `uncompressed` or undefined if it has not been previously compressed by this compressor.
+     */
+    tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
+}
 
 /* Excluded from this release type: IIdCompressorCore */
 
 /* Excluded from this release type: isStableId */
 
-/* Excluded from this release type: ITelemetryBaseLogger */
-
-/* Excluded from this release type: OpSpaceCompressedId */
+/**
+ * A compressed ID that has been normalized into "op space".
+ * Serialized/persisted structures (e.g. ops) should use op-space IDs as a performance optimization, as they require less normalizing when
+ * received by a remote client due to the fact that op space for a given compressor is session space for all other compressors.
+ * @public
+ */
+export declare type OpSpaceCompressedId = number & {
+    readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
+};
 
 /* Excluded from this release type: SerializedIdCompressor */
 
@@ -30,10 +140,33 @@ import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
 
 /* Excluded from this release type: SerializedIdCompressorWithOngoingSession */
 
-/* Excluded from this release type: SessionId */
-
-/* Excluded from this release type: SessionSpaceCompressedId */
-
-/* Excluded from this release type: StableId */
+/**
+ * A StableId which is suitable for use as a session identifier
+ * @public
+ */
+export declare type SessionId = StableId & {
+    readonly SessionId: "4498f850-e14e-4be9-8db0-89ec00997e58";
+};
+
+/**
+ * A compressed ID that has been normalized into "session space" (see `IdCompressor` for more).
+ * Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to
+ * the scope of the session (i.e. compressor) that produced them.
+ * @public
+ */
+export declare type SessionSpaceCompressedId = number & {
+    readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e";
+};
+
+/**
+ * A version 4, variant 1 uuid (https://datatracker.ietf.org/doc/html/rfc4122).
+ * A 128-bit Universally Unique IDentifier. Represented here
+ * with a string of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
+ * where x is a lowercase hex digit.
+ * @public
+ */
+export declare type StableId = string & {
+    readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a";
+};
 
 export { }

package/dist/id-compressor-untrimmed.d.ts

@@ -73,6 +73,7 @@ export declare class IdCompressor implements IIdCompressor, IIdCompressorCore {
     private nextRequestedClusterSize;
     private telemetryLocalIdCount;
     private telemetryEagerFinalIdCount;
+    private ongoingGhostSession?;
     private constructor();
     /**
      * @deprecated Use `createIdCompressor` instead.
@@ -83,6 +84,10 @@ export declare class IdCompressor implements IIdCompressor, IIdCompressorCore {
      */
     static create(sessionId: SessionId, logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
     generateCompressedId(): SessionSpaceCompressedId;
+    /**
+     * {@inheritdoc IIdCompressorCore.beginGhostSession}
+     */
+    beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): void;
     private generateNextLocalId;
     takeNextCreationRange(): IdCreationRange;
     private static assertValidRange;
@@ -97,6 +102,7 @@ export declare class IdCompressor implements IIdCompressor, IIdCompressorCore {
     serialize(withSession: false): SerializedIdCompressorWithNoSession;
     static deserialize(serialized: SerializedIdCompressorWithOngoingSession): IdCompressor;
     static deserialize(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId): IdCompressor;
+    private static deserialize2_0;
     equals(other: IdCompressor, includeLocalState: boolean): boolean;
 }
 
@@ -186,7 +192,7 @@ export declare interface IdCreationRange {
  *
  * 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.
- * @alpha
+ * @public
  */
 export declare interface IIdCompressor {
     localSessionId: SessionId;
@@ -248,6 +254,27 @@ export declare interface IIdCompressorCore {
      * @param range - the range of session-local IDs to finalize.
      */
     finalizeCreationRange(range: IdCreationRange): void;
+    /**
+     * Run a callback that is performed from the perspective of a special "ghost" session.
+     * Any ids generated by this session will be immediately finalized on the local client as if
+     * they were created by a remote client with `ghostSessionId`.
+     *
+     * *WARNING:* This API requires an external consensus mechanism to safely use:
+     * In an attached container (i.e. multiple clients may have the document loaded), all clients must guarantee that:
+     * - They invoke this API starting from the same finalized creation ranges
+     * - This API is invoked with the same ghost session id
+     * - `ghostSessionCallback` deterministically mints the same number of ids on each client within the ghost session
+     * Failure to meet these requirement will result in divergence across clients and eventual consistency errors.
+     * While the ghost sesion callback is running, IdCompressor does not support serialization.
+     * @remarks This API is primarily intended for data migration scenarios which are able to deterministically transform
+     * data in some format into data in a new format.
+     * The first requirement (that all clients must invoke the API with the same finalized creation ranges) is guaranteed
+     * for this scenario because the data transformation callback occurs at a specific ack within the op stream on all
+     * clients, and clients don't finalize creation ranges for local changes they might have at this point in time.
+     * @param ghostSessionId - The session id that minted ids generated within `ghostSessionCallback` should be attributed to.
+     * @param ghostSessionCallback - Callback which mints ids attributed to the ghost session.
+     */
+    beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): any;
     /**
      * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `IdCompressor.deserialize()`.
      * This includes finalized state as well as un-finalized state and is therefore suitable for use in offline scenarios.
@@ -271,7 +298,7 @@ export declare function isStableId(str: string): str is StableId;
  * A compressed ID that has been normalized into "op space".
  * Serialized/persisted structures (e.g. ops) should use op-space IDs as a performance optimization, as they require less normalizing when
  * received by a remote client due to the fact that op space for a given compressor is session space for all other compressors.
- * @alpha
+ * @public
  */
 export declare type OpSpaceCompressedId = number & {
     readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
@@ -303,7 +330,7 @@ export declare type SerializedIdCompressorWithOngoingSession = SerializedIdCompr
 
 /**
  * A StableId which is suitable for use as a session identifier
- * @alpha
+ * @public
  */
 export declare type SessionId = StableId & {
     readonly SessionId: "4498f850-e14e-4be9-8db0-89ec00997e58";
@@ -313,7 +340,7 @@ export declare type SessionId = StableId & {
  * A compressed ID that has been normalized into "session space" (see `IdCompressor` for more).
  * Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to
  * the scope of the session (i.e. compressor) that produced them.
- * @alpha
+ * @public
  */
 export declare type SessionSpaceCompressedId = number & {
     readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e";
@@ -324,7 +351,7 @@ export declare type SessionSpaceCompressedId = number & {
  * A 128-bit Universally Unique IDentifier. Represented here
  * with a string of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
  * where x is a lowercase hex digit.
- * @alpha
+ * @public
  */
 export declare type StableId = string & {
     readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a";