@fluidframework/core-interfaces 2.0.0-rc.3.0.3 → 2.0.0-rc.4.0.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @fluidframework/core-interfaces
 
+## 2.0.0-rc.4.0.0
+
+### Minor Changes
+
+-   Deprecated members of IFluidHandle are split off into new IFluidHandleInternal interface [96872186d0](https://github.com/microsoft/FluidFramework/commit/96872186d0d0f245c1fece7d19b3743e501679b6)
+
+    Split IFluidHandle into two interfaces, `IFluidHandle` and `IFluidHandleInternal`.
+    Code depending on the previously deprecated members of IFluidHandle can access them by using `toFluidHandleInternal` from `@fluidframework/runtime-utils/legacy`.
+
+    External implementation of the `IFluidHandle` interface are not supported: this change makes the typing better convey this using the `ErasedType` pattern.
+    Any existing and previously working, and now broken, external implementations of `IFluidHandle` should still work at runtime, but will need some unsafe type casts to compile.
+    Such handle implementation may break in the future and thus should be replaced with use of handles produced by the Fluid Framework client packages.
+
 ## 2.0.0-rc.3.0.0
 
 ### Major Changes

package/api-report/core-interfaces.api.md

@@ -28,6 +28,9 @@ export const FluidErrorTypes: {
 // @alpha (undocumented)
 export type FluidErrorTypes = (typeof FluidErrorTypes)[keyof typeof FluidErrorTypes];
 
+// @public
+export const fluidHandleSymbol: unique symbol;
+
 // @public
 export type FluidObject<T = unknown> = {
     [P in FluidObjectProviderKeys<T>]?: T[P];
@@ -237,16 +240,11 @@ export type IEventTransformer<TThis, TEvent extends IEvent> = TEvent extends {
 } ? TransformedEvent<TThis, E0, A0> : TransformedEvent<TThis, string, any[]>;
 
 // @public (undocumented)
-export const IFluidHandle: keyof IProvideFluidHandle;
+export const IFluidHandle = "IFluidHandle";
 
 // @public
-export interface IFluidHandle<T = FluidObject & IFluidLoadable> extends IProvideFluidHandle {
-    // @deprecated (undocumented)
-    readonly absolutePath: string;
-    // @deprecated (undocumented)
-    attachGraph(): void;
-    // @deprecated (undocumented)
-    bind(handle: IFluidHandle): void;
+export interface IFluidHandle<out T = unknown> {
+    readonly [fluidHandleSymbol]: IFluidHandleErased<T>;
     get(): Promise<T>;
     readonly isAttached: boolean;
 }
@@ -264,6 +262,17 @@ export interface IFluidHandleContext extends IProvideFluidHandleContext {
     readonly routeContext?: IFluidHandleContext;
 }
 
+// @public
+export interface IFluidHandleErased<T> extends ErasedType<readonly ["IFluidHandle", T]> {
+}
+
+// @alpha
+export interface IFluidHandleInternal<out T = unknown> extends IFluidHandle<T>, IProvideFluidHandle {
+    readonly absolutePath: string;
+    attachGraph(): void;
+    bind(handle: IFluidHandleInternal): void;
+}
+
 // @public (undocumented)
 export const IFluidLoadable: keyof IProvideFluidLoadable;
 
@@ -291,15 +300,15 @@ export interface IGenericError extends IErrorBase {
     readonly errorType: typeof FluidErrorTypes.genericError;
 }
 
-// @internal
+// @alpha
 export interface ILoggingError extends Error {
     getTelemetryProperties(): ITelemetryBaseProperties;
 }
 
-// @public (undocumented)
+// @alpha @deprecated (undocumented)
 export interface IProvideFluidHandle {
-    // (undocumented)
-    readonly IFluidHandle: IFluidHandle;
+    // @deprecated (undocumented)
+    readonly [IFluidHandle]: IFluidHandleInternal;
 }
 
 // @public (undocumented)

package/dist/handles.d.ts

@@ -2,9 +2,8 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import type { IFluidLoadable } from "./fluidLoadable.js";
+import { type ErasedType } from "./erasedType.js";
 import type { IRequest, IResponse } from "./fluidRouter.js";
-import type { FluidObject } from "./provider.js";
 /**
  * @public
  */
@@ -41,45 +40,88 @@ export interface IFluidHandleContext extends IProvideFluidHandleContext {
 }
 /**
  * @public
+ * @privateRemarks
+ * This really should be deprecated and alpha, but since its a merged export with the public interface,
+ * it can't have its own docs or different tags.
  */
-export declare const IFluidHandle: keyof IProvideFluidHandle;
+export declare const IFluidHandle = "IFluidHandle";
 /**
- * @public
+ * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+ * @alpha
  */
 export interface IProvideFluidHandle {
-    readonly IFluidHandle: IFluidHandle;
+    /**
+     * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+     * @privateRemarks
+     * This field must be kept so that code from before 2.0.0-rc.4.0.0 (When fluidHandleSymbol was added) still detects handles.
+     * This is required due to some use-cases mixing package versions.
+     * More details in packages/runtime/runtime-utils/src/handles.ts and on {@link fluidHandleSymbol}.
+     */
+    readonly [IFluidHandle]: IFluidHandleInternal;
 }
 /**
  * Handle to a shared {@link FluidObject}.
- * @public
+ * @alpha
  */
-export interface IFluidHandle<T = FluidObject & IFluidLoadable> extends IProvideFluidHandle {
+export interface IFluidHandleInternal<out T = unknown> extends IFluidHandle<T>, IProvideFluidHandle {
     /**
-     * @deprecated Do not use handle's path for routing. Use `get` to get the underlying object.
-     *
      * The absolute path to the handle context from the root.
      */
     readonly absolutePath: string;
     /**
-     * Flag indicating whether or not the entity has services attached.
-     */
-    readonly isAttached: boolean;
-    /**
-     * @deprecated To be removed. This is part of an internal API surface and should not be called.
-     *
      * Runs through the graph and attach the bounded handles.
      */
     attachGraph(): void;
+    /**
+     * Binds the given handle to this one or attach the given handle if this handle is attached.
+     * A bound handle will also be attached once this handle is attached.
+     */
+    bind(handle: IFluidHandleInternal): void;
+}
+/**
+ * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
+ *
+ * @remarks
+ * To narrow arbitrary objects to handles do not simply check for this symbol:
+ * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility
+ * with older implementations of handles that may exist due to dynamic code loading of older packages.
+ *
+ * @privateRemarks
+ * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.
+ * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.
+ * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:
+ * @public
+ */
+export declare const fluidHandleSymbol: unique symbol;
+/**
+ * Handle to a shared {@link FluidObject}.
+ * @public
+ */
+export interface IFluidHandle<out T = unknown> {
+    /**
+     * Flag indicating whether or not the entity has services attached.
+     */
+    readonly isAttached: boolean;
     /**
      * Returns a promise to the Fluid Object referenced by the handle.
      */
     get(): Promise<T>;
     /**
-     * @deprecated To be removed. This is part of an internal API surface and should not be called.
+     * Symbol used to mark an object as a {@link (IFluidHandle:interface)}
+     * and to recover the underlying handle implementation.
      *
-     * Binds the given handle to this one or attach the given handle if this handle is attached.
-     * A bound handle will also be attached once this handle is attached.
+     * @privateRemarks
+     * Used to recover {@link IFluidHandleInternal}, see {@link toFluidHandleInternal}.
      */
-    bind(handle: IFluidHandle): void;
+    readonly [fluidHandleSymbol]: IFluidHandleErased<T>;
+}
+/**
+ * A type erased Fluid Handle.
+ * These can only be produced by the Fluid Framework and provide the implementation details needed to power {@link (IFluidHandle:interface)}.
+ * @privateRemarks
+ * Created from {@link IFluidHandleInternal} using {@link toFluidHandleErased}.
+ * @public
+ */
+export interface IFluidHandleErased<T> extends ErasedType<readonly ["IFluidHandle", T]> {
 }
 //# sourceMappingURL=handles.d.ts.map

package/dist/handles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,0BAAkD,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,0BAA0B;IACtE;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB,aAAa,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,mBAAoC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY,CAE5B,CAAC,GAAG,WAAW,GAAG,cAAc,CAC/B,SAAQ,mBAAmB;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;;;OAIG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;OAEG;IACH,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAElB;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CACjC"}
+{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,0BAAkD,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,0BAA0B;IACtE;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB,aAAa,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB,CAEpC,GAAG,CAAC,CAAC,GAAG,OAAO,CACd,SAAQ,YAAY,CAAC,CAAC,CAAC,EACvB,mBAAmB;IACpB;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAEtC,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO;IAC5C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAElB;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;CACpD;AAED;;;;;;GAMG;AAEH,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,SAAS,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;CAAG"}

package/dist/handles.js

@@ -4,13 +4,31 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IFluidHandle = exports.IFluidHandleContext = void 0;
+exports.fluidHandleSymbol = exports.IFluidHandle = exports.IFluidHandleContext = void 0;
 /**
  * @public
  */
 exports.IFluidHandleContext = "IFluidHandleContext";
 /**
  * @public
+ * @privateRemarks
+ * This really should be deprecated and alpha, but since its a merged export with the public interface,
+ * it can't have its own docs or different tags.
  */
 exports.IFluidHandle = "IFluidHandle";
+/**
+ * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
+ *
+ * @remarks
+ * To narrow arbitrary objects to handles do not simply check for this symbol:
+ * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility
+ * with older implementations of handles that may exist due to dynamic code loading of older packages.
+ *
+ * @privateRemarks
+ * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.
+ * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.
+ * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:
+ * @public
+ */
+exports.fluidHandleSymbol = Symbol.for("FluidHandle-3978c7cf-4675-49ba-a20c-bf35efbf43da");
 //# sourceMappingURL=handles.js.map

package/dist/handles.js.map

@@ -1 +1 @@
-{"version":3,"file":"handles.js","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAMH;;GAEG;AACU,QAAA,mBAAmB,GAAqC,qBAAqB,CAAC;AAsC3F;;GAEG;AACU,QAAA,YAAY,GAA8B,cAAc,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IFluidLoadable } from \"./fluidLoadable.js\";\nimport type { IRequest, IResponse } from \"./fluidRouter.js\";\nimport type { FluidObject } from \"./provider.js\";\n\n/**\n * @public\n */\nexport const IFluidHandleContext: keyof IProvideFluidHandleContext = \"IFluidHandleContext\";\n\n/**\n * @public\n */\nexport interface IProvideFluidHandleContext {\n\treadonly IFluidHandleContext: IFluidHandleContext;\n}\n\n/**\n * Describes a routing context from which other `IFluidHandleContext`s are defined.\n * @public\n */\nexport interface IFluidHandleContext extends IProvideFluidHandleContext {\n\t/**\n\t * The absolute path to the handle context from the root.\n\t */\n\treadonly absolutePath: string;\n\n\t/**\n\t * The parent IFluidHandleContext that has provided a route path to this IFluidHandleContext or undefined\n\t * at the root.\n\t */\n\treadonly routeContext?: IFluidHandleContext;\n\n\t/**\n\t * Flag indicating whether or not the entity has services attached.\n\t */\n\treadonly isAttached: boolean;\n\n\t/**\n\t * Runs through the graph and attach the bounded handles.\n\t */\n\tattachGraph(): void;\n\n\tresolveHandle(request: IRequest): Promise<IResponse>;\n}\n\n/**\n * @public\n */\nexport const IFluidHandle: keyof IProvideFluidHandle = \"IFluidHandle\";\n\n/**\n * @public\n */\nexport interface IProvideFluidHandle {\n\treadonly IFluidHandle: IFluidHandle;\n}\n\n/**\n * Handle to a shared {@link FluidObject}.\n * @public\n */\nexport interface IFluidHandle<\n\t// REVIEW: Constrain `T` to something? How do we support dds and datastores safely?\n\tT = FluidObject & IFluidLoadable,\n> extends IProvideFluidHandle {\n\t/**\n\t * @deprecated Do not use handle's path for routing. Use `get` to get the underlying object.\n\t *\n\t * The absolute path to the handle context from the root.\n\t */\n\treadonly absolutePath: string;\n\n\t/**\n\t * Flag indicating whether or not the entity has services attached.\n\t */\n\treadonly isAttached: boolean;\n\n\t/**\n\t * @deprecated To be removed. This is part of an internal API surface and should not be called.\n\t *\n\t * Runs through the graph and attach the bounded handles.\n\t */\n\tattachGraph(): void;\n\n\t/**\n\t * Returns a promise to the Fluid Object referenced by the handle.\n\t */\n\tget(): Promise<T>;\n\n\t/**\n\t * @deprecated To be removed. This is part of an internal API surface and should not be called.\n\t *\n\t * Binds the given handle to this one or attach the given handle if this handle is attached.\n\t * A bound handle will also be attached once this handle is attached.\n\t */\n\tbind(handle: IFluidHandle): void;\n}\n"]}
+{"version":3,"file":"handles.js","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAKH;;GAEG;AACU,QAAA,mBAAmB,GAAqC,qBAAqB,CAAC;AAsC3F;;;;;GAKG;AACU,QAAA,YAAY,GAAG,cAAc,CAAC;AA2C3C;;;;;;;;;;;;;GAaG;AACU,QAAA,iBAAiB,GAAkB,MAAM,CAAC,GAAG,CACzD,kDAAkD,CAClD,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { type ErasedType } from \"./erasedType.js\";\nimport type { IRequest, IResponse } from \"./fluidRouter.js\";\n\n/**\n * @public\n */\nexport const IFluidHandleContext: keyof IProvideFluidHandleContext = \"IFluidHandleContext\";\n\n/**\n * @public\n */\nexport interface IProvideFluidHandleContext {\n\treadonly IFluidHandleContext: IFluidHandleContext;\n}\n\n/**\n * Describes a routing context from which other `IFluidHandleContext`s are defined.\n * @public\n */\nexport interface IFluidHandleContext extends IProvideFluidHandleContext {\n\t/**\n\t * The absolute path to the handle context from the root.\n\t */\n\treadonly absolutePath: string;\n\n\t/**\n\t * The parent IFluidHandleContext that has provided a route path to this IFluidHandleContext or undefined\n\t * at the root.\n\t */\n\treadonly routeContext?: IFluidHandleContext;\n\n\t/**\n\t * Flag indicating whether or not the entity has services attached.\n\t */\n\treadonly isAttached: boolean;\n\n\t/**\n\t * Runs through the graph and attach the bounded handles.\n\t */\n\tattachGraph(): void;\n\n\tresolveHandle(request: IRequest): Promise<IResponse>;\n}\n\n/**\n * @public\n * @privateRemarks\n * This really should be deprecated and alpha, but since its a merged export with the public interface,\n * it can't have its own docs or different tags.\n */\nexport const IFluidHandle = \"IFluidHandle\";\n\n/**\n * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.\n * @alpha\n */\nexport interface IProvideFluidHandle {\n\t/**\n\t * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.\n\t * @privateRemarks\n\t * This field must be kept so that code from before 2.0.0-rc.4.0.0 (When fluidHandleSymbol was added) still detects handles.\n\t * This is required due to some use-cases mixing package versions.\n\t * More details in packages/runtime/runtime-utils/src/handles.ts and on {@link fluidHandleSymbol}.\n\t */\n\treadonly [IFluidHandle]: IFluidHandleInternal;\n}\n\n/**\n * Handle to a shared {@link FluidObject}.\n * @alpha\n */\nexport interface IFluidHandleInternal<\n\t// REVIEW: Constrain `T` to something? How do we support dds and datastores safely?\n\tout T = unknown, // FluidObject & IFluidLoadable,\n> extends IFluidHandle<T>,\n\t\tIProvideFluidHandle {\n\t/**\n\t * The absolute path to the handle context from the root.\n\t */\n\treadonly absolutePath: string;\n\n\t/**\n\t * Runs through the graph and attach the bounded handles.\n\t */\n\tattachGraph(): void;\n\n\t/**\n\t * Binds the given handle to this one or attach the given handle if this handle is attached.\n\t * A bound handle will also be attached once this handle is attached.\n\t */\n\tbind(handle: IFluidHandleInternal): void;\n}\n\n/**\n * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.\n *\n * @remarks\n * To narrow arbitrary objects to handles do not simply check for this symbol:\n * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility\n * with older implementations of handles that may exist due to dynamic code loading of older packages.\n *\n * @privateRemarks\n * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.\n * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.\n * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:\n * @public\n */\nexport const fluidHandleSymbol: unique symbol = Symbol.for(\n\t\"FluidHandle-3978c7cf-4675-49ba-a20c-bf35efbf43da\",\n);\n\n/**\n * Handle to a shared {@link FluidObject}.\n * @public\n */\nexport interface IFluidHandle<out T = unknown> {\n\t/**\n\t * Flag indicating whether or not the entity has services attached.\n\t */\n\treadonly isAttached: boolean;\n\n\t/**\n\t * Returns a promise to the Fluid Object referenced by the handle.\n\t */\n\tget(): Promise<T>;\n\n\t/**\n\t * Symbol used to mark an object as a {@link (IFluidHandle:interface)}\n\t * and to recover the underlying handle implementation.\n\t *\n\t * @privateRemarks\n\t * Used to recover {@link IFluidHandleInternal}, see {@link toFluidHandleInternal}.\n\t */\n\treadonly [fluidHandleSymbol]: IFluidHandleErased<T>;\n}\n\n/**\n * A type erased Fluid Handle.\n * These can only be produced by the Fluid Framework and provide the implementation details needed to power {@link (IFluidHandle:interface)}.\n * @privateRemarks\n * Created from {@link IFluidHandleInternal} using {@link toFluidHandleErased}.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-interface\nexport interface IFluidHandleErased<T> extends ErasedType<readonly [\"IFluidHandle\", T]> {}\n"]}

package/dist/index.d.ts

@@ -9,8 +9,8 @@ export type { ExtendEventProvider, IErrorEvent, IEvent, IEventProvider, IEventTh
 export type { IProvideFluidLoadable, IProvideFluidRunnable } from "./fluidLoadable.js";
 export { IFluidLoadable, IFluidRunnable } from "./fluidLoadable.js";
 export type { IRequest, IRequestHeader, IResponse } from "./fluidRouter.js";
-export type { IProvideFluidHandleContext, IProvideFluidHandle } from "./handles.js";
-export { IFluidHandleContext, IFluidHandle } from "./handles.js";
+export type { IProvideFluidHandleContext, IProvideFluidHandle, IFluidHandleInternal, IFluidHandleErased, } from "./handles.js";
+export { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from "./handles.js";
 export type { ILoggingError, ITelemetryBaseEvent, ITelemetryBaseLogger, ITelemetryBaseProperties, Tagged, TelemetryBaseEventPropertyType, } from "./logger.js";
 export { LogLevel } from "./logger.js";
 export type { FluidObjectProviderKeys, FluidObject, FluidObjectKeys } from "./provider.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,YAAY,EACX,mBAAmB,EACnB,WAAW,EACX,MAAM,EACN,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,EAC5B,gBAAgB,GAChB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAKpE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5E,YAAY,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjE,YAAY,EACX,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,MAAM,EACN,8BAA8B,GAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,uBAAuB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3F,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,YAAY,EACX,mBAAmB,EACnB,WAAW,EACX,MAAM,EACN,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,EAC5B,gBAAgB,GAChB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAKpE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5E,YAAY,EACX,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEpF,YAAY,EACX,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,MAAM,EACN,8BAA8B,GAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,uBAAuB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3F,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -4,7 +4,7 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLevel = exports.IFluidHandle = exports.IFluidHandleContext = exports.IFluidRunnable = exports.IFluidLoadable = exports.FluidErrorTypes = void 0;
+exports.LogLevel = exports.fluidHandleSymbol = exports.IFluidHandle = exports.IFluidHandleContext = exports.IFluidRunnable = exports.IFluidLoadable = exports.FluidErrorTypes = void 0;
 var error_js_1 = require("./error.js");
 Object.defineProperty(exports, "FluidErrorTypes", { enumerable: true, get: function () { return error_js_1.FluidErrorTypes; } });
 var fluidLoadable_js_1 = require("./fluidLoadable.js");
@@ -13,6 +13,7 @@ Object.defineProperty(exports, "IFluidRunnable", { enumerable: true, get: functi
 var handles_js_1 = require("./handles.js");
 Object.defineProperty(exports, "IFluidHandleContext", { enumerable: true, get: function () { return handles_js_1.IFluidHandleContext; } });
 Object.defineProperty(exports, "IFluidHandle", { enumerable: true, get: function () { return handles_js_1.IFluidHandle; } });
+Object.defineProperty(exports, "fluidHandleSymbol", { enumerable: true, get: function () { return handles_js_1.fluidHandleSymbol; } });
 var logger_js_1 = require("./logger.js");
 Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return logger_js_1.LogLevel; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAKH,uCAA6C;AAApC,2GAAA,eAAe,OAAA;AAcxB,uDAAoE;AAA3D,kHAAA,cAAc,OAAA;AAAE,kHAAA,cAAc,OAAA;AAQvC,2CAAiE;AAAxD,iHAAA,mBAAmB,OAAA;AAAE,0GAAA,YAAY,OAAA;AAU1C,yCAAuC;AAA9B,qGAAA,QAAQ,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport type { IDisposable } from \"./disposable.js\";\n\nexport type { IErrorBase, IGenericError, IUsageError, IThrottlingWarning } from \"./error.js\";\nexport { FluidErrorTypes } from \"./error.js\";\n\nexport type {\n\tExtendEventProvider,\n\tIErrorEvent,\n\tIEvent,\n\tIEventProvider,\n\tIEventThisPlaceHolder,\n\tIEventTransformer,\n\tReplaceIEventThisPlaceHolder,\n\tTransformedEvent,\n} from \"./events.js\";\n\nexport type { IProvideFluidLoadable, IProvideFluidRunnable } from \"./fluidLoadable.js\";\nexport { IFluidLoadable, IFluidRunnable } from \"./fluidLoadable.js\";\n\n// TypeScript forgets the index signature when customers augment IRequestHeader if we export *.\n// So we export the explicit members as a workaround:\n// https://github.com/microsoft/TypeScript/issues/18877#issuecomment-476921038\nexport type { IRequest, IRequestHeader, IResponse } from \"./fluidRouter.js\";\n\nexport type { IProvideFluidHandleContext, IProvideFluidHandle } from \"./handles.js\";\nexport { IFluidHandleContext, IFluidHandle } from \"./handles.js\";\n\nexport type {\n\tILoggingError,\n\tITelemetryBaseEvent,\n\tITelemetryBaseLogger,\n\tITelemetryBaseProperties,\n\tTagged,\n\tTelemetryBaseEventPropertyType,\n} from \"./logger.js\";\nexport { LogLevel } from \"./logger.js\";\nexport type { FluidObjectProviderKeys, FluidObject, FluidObjectKeys } from \"./provider.js\";\nexport type { ConfigTypes, IConfigProviderBase } from \"./config.js\";\nexport type { ISignalEnvelope } from \"./messages.js\";\nexport type { ErasedType } from \"./erasedType.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAKH,uCAA6C;AAApC,2GAAA,eAAe,OAAA;AAcxB,uDAAoE;AAA3D,kHAAA,cAAc,OAAA;AAAE,kHAAA,cAAc,OAAA;AAavC,2CAAoF;AAA3E,iHAAA,mBAAmB,OAAA;AAAE,0GAAA,YAAY,OAAA;AAAE,+GAAA,iBAAiB,OAAA;AAU7D,yCAAuC;AAA9B,qGAAA,QAAQ,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport type { IDisposable } from \"./disposable.js\";\n\nexport type { IErrorBase, IGenericError, IUsageError, IThrottlingWarning } from \"./error.js\";\nexport { FluidErrorTypes } from \"./error.js\";\n\nexport type {\n\tExtendEventProvider,\n\tIErrorEvent,\n\tIEvent,\n\tIEventProvider,\n\tIEventThisPlaceHolder,\n\tIEventTransformer,\n\tReplaceIEventThisPlaceHolder,\n\tTransformedEvent,\n} from \"./events.js\";\n\nexport type { IProvideFluidLoadable, IProvideFluidRunnable } from \"./fluidLoadable.js\";\nexport { IFluidLoadable, IFluidRunnable } from \"./fluidLoadable.js\";\n\n// TypeScript forgets the index signature when customers augment IRequestHeader if we export *.\n// So we export the explicit members as a workaround:\n// https://github.com/microsoft/TypeScript/issues/18877#issuecomment-476921038\nexport type { IRequest, IRequestHeader, IResponse } from \"./fluidRouter.js\";\n\nexport type {\n\tIProvideFluidHandleContext,\n\tIProvideFluidHandle,\n\tIFluidHandleInternal,\n\tIFluidHandleErased,\n} from \"./handles.js\";\nexport { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from \"./handles.js\";\n\nexport type {\n\tILoggingError,\n\tITelemetryBaseEvent,\n\tITelemetryBaseLogger,\n\tITelemetryBaseProperties,\n\tTagged,\n\tTelemetryBaseEventPropertyType,\n} from \"./logger.js\";\nexport { LogLevel } from \"./logger.js\";\nexport type { FluidObjectProviderKeys, FluidObject, FluidObjectKeys } from \"./provider.js\";\nexport type { ConfigTypes, IConfigProviderBase } from \"./config.js\";\nexport type { ISignalEnvelope } from \"./messages.js\";\nexport type { ErasedType } from \"./erasedType.js\";\n"]}

package/dist/legacy.d.ts

@@ -9,7 +9,7 @@
  */
 
 export {
-	// public APIs
+	// @public APIs
 	ConfigTypes, 
 	ErasedType, 
 	ExtendEventProvider, 
@@ -26,8 +26,8 @@ export {
 	IEventTransformer, 
 	IFluidHandle, 
 	IFluidHandleContext, 
+	IFluidHandleErased, 
 	IFluidLoadable, 
-	IProvideFluidHandle, 
 	IProvideFluidHandleContext, 
 	IProvideFluidLoadable, 
 	IRequest, 
@@ -40,9 +40,13 @@ export {
 	ReplaceIEventThisPlaceHolder, 
 	Tagged, 
 	TelemetryBaseEventPropertyType, 
-	TransformedEvent,
+	TransformedEvent, 
+	fluidHandleSymbol,
  
-	// alpha APIs
+	// @alpha APIs
 	FluidErrorTypes, 
+	IFluidHandleInternal, 
+	ILoggingError, 
+	IProvideFluidHandle, 
 	IThrottlingWarning
 } from "./index.js";

package/dist/logger.d.ts

@@ -81,7 +81,7 @@ export interface ITelemetryErrorEvent extends ITelemetryBaseProperties {
 }
 /**
  * An error object that supports exporting its properties to be logged to telemetry
- * @internal
+ * @alpha
  */
 export interface ILoggingError extends Error {
     /**

package/dist/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAiDH;;;GAGG;AACU,QAAA,QAAQ,GAAG;IACvB,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE,EAAE,iBAAiB;CACnB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Property types that can be logged.\n *\n * @remarks Logging entire objects is considered extremely dangerous from a telemetry point of view because people can\n * easily add fields to objects that shouldn't be logged and not realize it's going to be logged.\n * General best practice is to explicitly log the fields you care about from objects.\n * @public\n */\nexport type TelemetryBaseEventPropertyType = string | number | boolean | undefined;\n\n/**\n * A property to be logged to telemetry may require a tag indicating the value may contain sensitive data.\n * This type wraps a value of the given type V in an object along with a string tag (type can be further specified as T).\n *\n * This indicates that the value should be organized or handled differently by loggers in various first or third\n * party scenarios. For example, tags are used to mark data that should not be stored in logs for privacy reasons.\n * @public\n */\nexport interface Tagged<V, T extends string = string> {\n\tvalue: V;\n\ttag: T;\n}\n\n/**\n * JSON-serializable properties, which will be logged with telemetry.\n * @public\n */\nexport interface ITelemetryBaseProperties {\n\t/**\n\t * Properties of a telemetry event. They are string-indexed, and their values restricted to a known set of\n\t * types (optionally \"wrapped\" with {@link Tagged}).\n\t */\n\t[index: string]: TelemetryBaseEventPropertyType | Tagged<TelemetryBaseEventPropertyType>;\n}\n\n/**\n * Base interface for logging telemetry statements.\n * Can contain any number of properties that get serialized as json payload.\n * @param category - category of the event, like \"error\", \"performance\", \"generic\", etc.\n * @param eventName - name of the event.\n * @public\n */\nexport interface ITelemetryBaseEvent extends ITelemetryBaseProperties {\n\tcategory: string;\n\teventName: string;\n}\n\n/**\n * Specify levels of the logs.\n * @public\n */\nexport const LogLevel = {\n\tverbose: 10, // To log any verbose event for example when you are debugging something.\n\tdefault: 20, // Default log level\n\terror: 30, // To log errors.\n} as const;\n\n/**\n * Specify a level to the log to filter out logs based on the level.\n * @public\n */\nexport type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];\n\n/**\n * Interface to output telemetry events.\n * Implemented by hosting app / loader\n * @public\n */\nexport interface ITelemetryBaseLogger {\n\tsend(event: ITelemetryBaseEvent, logLevel?: LogLevel): void;\n\n\tminLogLevel?: LogLevel;\n}\n\n/**\n * Error telemetry event.\n * Maps to category = \"error\"\n *\n * @deprecated For internal use within FluidFramework, use ITelemetryErrorEventExt in \\@fluidframework/telemetry-utils.\n * No replacement intended for FluidFramework consumers.\n * @public\n */\nexport interface ITelemetryErrorEvent extends ITelemetryBaseProperties {\n\teventName: string;\n}\n\n/**\n * An error object that supports exporting its properties to be logged to telemetry\n * @internal\n */\nexport interface ILoggingError extends Error {\n\t/**\n\t * Return all properties from this object that should be logged to telemetry\n\t */\n\tgetTelemetryProperties(): ITelemetryBaseProperties;\n}\n"]}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAiDH;;;GAGG;AACU,QAAA,QAAQ,GAAG;IACvB,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE,EAAE,iBAAiB;CACnB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Property types that can be logged.\n *\n * @remarks Logging entire objects is considered extremely dangerous from a telemetry point of view because people can\n * easily add fields to objects that shouldn't be logged and not realize it's going to be logged.\n * General best practice is to explicitly log the fields you care about from objects.\n * @public\n */\nexport type TelemetryBaseEventPropertyType = string | number | boolean | undefined;\n\n/**\n * A property to be logged to telemetry may require a tag indicating the value may contain sensitive data.\n * This type wraps a value of the given type V in an object along with a string tag (type can be further specified as T).\n *\n * This indicates that the value should be organized or handled differently by loggers in various first or third\n * party scenarios. For example, tags are used to mark data that should not be stored in logs for privacy reasons.\n * @public\n */\nexport interface Tagged<V, T extends string = string> {\n\tvalue: V;\n\ttag: T;\n}\n\n/**\n * JSON-serializable properties, which will be logged with telemetry.\n * @public\n */\nexport interface ITelemetryBaseProperties {\n\t/**\n\t * Properties of a telemetry event. They are string-indexed, and their values restricted to a known set of\n\t * types (optionally \"wrapped\" with {@link Tagged}).\n\t */\n\t[index: string]: TelemetryBaseEventPropertyType | Tagged<TelemetryBaseEventPropertyType>;\n}\n\n/**\n * Base interface for logging telemetry statements.\n * Can contain any number of properties that get serialized as json payload.\n * @param category - category of the event, like \"error\", \"performance\", \"generic\", etc.\n * @param eventName - name of the event.\n * @public\n */\nexport interface ITelemetryBaseEvent extends ITelemetryBaseProperties {\n\tcategory: string;\n\teventName: string;\n}\n\n/**\n * Specify levels of the logs.\n * @public\n */\nexport const LogLevel = {\n\tverbose: 10, // To log any verbose event for example when you are debugging something.\n\tdefault: 20, // Default log level\n\terror: 30, // To log errors.\n} as const;\n\n/**\n * Specify a level to the log to filter out logs based on the level.\n * @public\n */\nexport type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];\n\n/**\n * Interface to output telemetry events.\n * Implemented by hosting app / loader\n * @public\n */\nexport interface ITelemetryBaseLogger {\n\tsend(event: ITelemetryBaseEvent, logLevel?: LogLevel): void;\n\n\tminLogLevel?: LogLevel;\n}\n\n/**\n * Error telemetry event.\n * Maps to category = \"error\"\n *\n * @deprecated For internal use within FluidFramework, use ITelemetryErrorEventExt in \\@fluidframework/telemetry-utils.\n * No replacement intended for FluidFramework consumers.\n * @public\n */\nexport interface ITelemetryErrorEvent extends ITelemetryBaseProperties {\n\teventName: string;\n}\n\n/**\n * An error object that supports exporting its properties to be logged to telemetry\n * @alpha\n */\nexport interface ILoggingError extends Error {\n\t/**\n\t * Return all properties from this object that should be logged to telemetry\n\t */\n\tgetTelemetryProperties(): ITelemetryBaseProperties;\n}\n"]}

package/dist/public.d.ts

@@ -9,7 +9,7 @@
  */
 
 export {
-	// public APIs
+	// @public APIs
 	ConfigTypes, 
 	ErasedType, 
 	ExtendEventProvider, 
@@ -26,8 +26,8 @@ export {
 	IEventTransformer, 
 	IFluidHandle, 
 	IFluidHandleContext, 
+	IFluidHandleErased, 
 	IFluidLoadable, 
-	IProvideFluidHandle, 
 	IProvideFluidHandleContext, 
 	IProvideFluidLoadable, 
 	IRequest, 
@@ -40,5 +40,6 @@ export {
 	ReplaceIEventThisPlaceHolder, 
 	Tagged, 
 	TelemetryBaseEventPropertyType, 
-	TransformedEvent
+	TransformedEvent, 
+	fluidHandleSymbol
 } from "./index.js";

package/lib/handles.d.ts

@@ -2,9 +2,8 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import type { IFluidLoadable } from "./fluidLoadable.js";
+import { type ErasedType } from "./erasedType.js";
 import type { IRequest, IResponse } from "./fluidRouter.js";
-import type { FluidObject } from "./provider.js";
 /**
  * @public
  */
@@ -41,45 +40,88 @@ export interface IFluidHandleContext extends IProvideFluidHandleContext {
 }
 /**
  * @public
+ * @privateRemarks
+ * This really should be deprecated and alpha, but since its a merged export with the public interface,
+ * it can't have its own docs or different tags.
  */
-export declare const IFluidHandle: keyof IProvideFluidHandle;
+export declare const IFluidHandle = "IFluidHandle";
 /**
- * @public
+ * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+ * @alpha
  */
 export interface IProvideFluidHandle {
-    readonly IFluidHandle: IFluidHandle;
+    /**
+     * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+     * @privateRemarks
+     * This field must be kept so that code from before 2.0.0-rc.4.0.0 (When fluidHandleSymbol was added) still detects handles.
+     * This is required due to some use-cases mixing package versions.
+     * More details in packages/runtime/runtime-utils/src/handles.ts and on {@link fluidHandleSymbol}.
+     */
+    readonly [IFluidHandle]: IFluidHandleInternal;
 }
 /**
  * Handle to a shared {@link FluidObject}.
- * @public
+ * @alpha
  */
-export interface IFluidHandle<T = FluidObject & IFluidLoadable> extends IProvideFluidHandle {
+export interface IFluidHandleInternal<out T = unknown> extends IFluidHandle<T>, IProvideFluidHandle {
     /**
-     * @deprecated Do not use handle's path for routing. Use `get` to get the underlying object.
-     *
      * The absolute path to the handle context from the root.
      */
     readonly absolutePath: string;
     /**
-     * Flag indicating whether or not the entity has services attached.
-     */
-    readonly isAttached: boolean;
-    /**
-     * @deprecated To be removed. This is part of an internal API surface and should not be called.
-     *
      * Runs through the graph and attach the bounded handles.
      */
     attachGraph(): void;
+    /**
+     * Binds the given handle to this one or attach the given handle if this handle is attached.
+     * A bound handle will also be attached once this handle is attached.
+     */
+    bind(handle: IFluidHandleInternal): void;
+}
+/**
+ * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
+ *
+ * @remarks
+ * To narrow arbitrary objects to handles do not simply check for this symbol:
+ * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility
+ * with older implementations of handles that may exist due to dynamic code loading of older packages.
+ *
+ * @privateRemarks
+ * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.
+ * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.
+ * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:
+ * @public
+ */
+export declare const fluidHandleSymbol: unique symbol;
+/**
+ * Handle to a shared {@link FluidObject}.
+ * @public
+ */
+export interface IFluidHandle<out T = unknown> {
+    /**
+     * Flag indicating whether or not the entity has services attached.
+     */
+    readonly isAttached: boolean;
     /**
      * Returns a promise to the Fluid Object referenced by the handle.
      */
     get(): Promise<T>;
     /**
-     * @deprecated To be removed. This is part of an internal API surface and should not be called.
+     * Symbol used to mark an object as a {@link (IFluidHandle:interface)}
+     * and to recover the underlying handle implementation.
      *
-     * Binds the given handle to this one or attach the given handle if this handle is attached.
-     * A bound handle will also be attached once this handle is attached.
+     * @privateRemarks
+     * Used to recover {@link IFluidHandleInternal}, see {@link toFluidHandleInternal}.
      */
-    bind(handle: IFluidHandle): void;
+    readonly [fluidHandleSymbol]: IFluidHandleErased<T>;
+}
+/**
+ * A type erased Fluid Handle.
+ * These can only be produced by the Fluid Framework and provide the implementation details needed to power {@link (IFluidHandle:interface)}.
+ * @privateRemarks
+ * Created from {@link IFluidHandleInternal} using {@link toFluidHandleErased}.
+ * @public
+ */
+export interface IFluidHandleErased<T> extends ErasedType<readonly ["IFluidHandle", T]> {
 }
 //# sourceMappingURL=handles.d.ts.map

package/lib/handles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,0BAAkD,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,0BAA0B;IACtE;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB,aAAa,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,mBAAoC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY,CAE5B,CAAC,GAAG,WAAW,GAAG,cAAc,CAC/B,SAAQ,mBAAmB;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;;;OAIG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;OAEG;IACH,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAElB;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CACjC"}
+{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,0BAAkD,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,0BAA0B;IACtE;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB,aAAa,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB,CAEpC,GAAG,CAAC,CAAC,GAAG,OAAO,CACd,SAAQ,YAAY,CAAC,CAAC,CAAC,EACvB,mBAAmB;IACpB;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAEtC,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO;IAC5C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAElB;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;CACpD;AAED;;;;;;GAMG;AAEH,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,SAAS,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;CAAG"}

package/lib/handles.js

@@ -8,6 +8,24 @@
 export const IFluidHandleContext = "IFluidHandleContext";
 /**
  * @public
+ * @privateRemarks
+ * This really should be deprecated and alpha, but since its a merged export with the public interface,
+ * it can't have its own docs or different tags.
  */
 export const IFluidHandle = "IFluidHandle";
+/**
+ * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
+ *
+ * @remarks
+ * To narrow arbitrary objects to handles do not simply check for this symbol:
+ * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility
+ * with older implementations of handles that may exist due to dynamic code loading of older packages.
+ *
+ * @privateRemarks
+ * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.
+ * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.
+ * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:
+ * @public
+ */
+export const fluidHandleSymbol = Symbol.for("FluidHandle-3978c7cf-4675-49ba-a20c-bf35efbf43da");
 //# sourceMappingURL=handles.js.map

package/lib/handles.js.map

@@ -1 +1 @@
-{"version":3,"file":"handles.js","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAqC,qBAAqB,CAAC;AAsC3F;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAA8B,cAAc,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IFluidLoadable } from \"./fluidLoadable.js\";\nimport type { IRequest, IResponse } from \"./fluidRouter.js\";\nimport type { FluidObject } from \"./provider.js\";\n\n/**\n * @public\n */\nexport const IFluidHandleContext: keyof IProvideFluidHandleContext = \"IFluidHandleContext\";\n\n/**\n * @public\n */\nexport interface IProvideFluidHandleContext {\n\treadonly IFluidHandleContext: IFluidHandleContext;\n}\n\n/**\n * Describes a routing context from which other `IFluidHandleContext`s are defined.\n * @public\n */\nexport interface IFluidHandleContext extends IProvideFluidHandleContext {\n\t/**\n\t * The absolute path to the handle context from the root.\n\t */\n\treadonly absolutePath: string;\n\n\t/**\n\t * The parent IFluidHandleContext that has provided a route path to this IFluidHandleContext or undefined\n\t * at the root.\n\t */\n\treadonly routeContext?: IFluidHandleContext;\n\n\t/**\n\t * Flag indicating whether or not the entity has services attached.\n\t */\n\treadonly isAttached: boolean;\n\n\t/**\n\t * Runs through the graph and attach the bounded handles.\n\t */\n\tattachGraph(): void;\n\n\tresolveHandle(request: IRequest): Promise<IResponse>;\n}\n\n/**\n * @public\n */\nexport const IFluidHandle: keyof IProvideFluidHandle = \"IFluidHandle\";\n\n/**\n * @public\n */\nexport interface IProvideFluidHandle {\n\treadonly IFluidHandle: IFluidHandle;\n}\n\n/**\n * Handle to a shared {@link FluidObject}.\n * @public\n */\nexport interface IFluidHandle<\n\t// REVIEW: Constrain `T` to something? How do we support dds and datastores safely?\n\tT = FluidObject & IFluidLoadable,\n> extends IProvideFluidHandle {\n\t/**\n\t * @deprecated Do not use handle's path for routing. Use `get` to get the underlying object.\n\t *\n\t * The absolute path to the handle context from the root.\n\t */\n\treadonly absolutePath: string;\n\n\t/**\n\t * Flag indicating whether or not the entity has services attached.\n\t */\n\treadonly isAttached: boolean;\n\n\t/**\n\t * @deprecated To be removed. This is part of an internal API surface and should not be called.\n\t *\n\t * Runs through the graph and attach the bounded handles.\n\t */\n\tattachGraph(): void;\n\n\t/**\n\t * Returns a promise to the Fluid Object referenced by the handle.\n\t */\n\tget(): Promise<T>;\n\n\t/**\n\t * @deprecated To be removed. This is part of an internal API surface and should not be called.\n\t *\n\t * Binds the given handle to this one or attach the given handle if this handle is attached.\n\t * A bound handle will also be attached once this handle is attached.\n\t */\n\tbind(handle: IFluidHandle): void;\n}\n"]}
+{"version":3,"file":"handles.js","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAqC,qBAAqB,CAAC;AAsC3F;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC;AA2C3C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAkB,MAAM,CAAC,GAAG,CACzD,kDAAkD,CAClD,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { type ErasedType } from \"./erasedType.js\";\nimport type { IRequest, IResponse } from \"./fluidRouter.js\";\n\n/**\n * @public\n */\nexport const IFluidHandleContext: keyof IProvideFluidHandleContext = \"IFluidHandleContext\";\n\n/**\n * @public\n */\nexport interface IProvideFluidHandleContext {\n\treadonly IFluidHandleContext: IFluidHandleContext;\n}\n\n/**\n * Describes a routing context from which other `IFluidHandleContext`s are defined.\n * @public\n */\nexport interface IFluidHandleContext extends IProvideFluidHandleContext {\n\t/**\n\t * The absolute path to the handle context from the root.\n\t */\n\treadonly absolutePath: string;\n\n\t/**\n\t * The parent IFluidHandleContext that has provided a route path to this IFluidHandleContext or undefined\n\t * at the root.\n\t */\n\treadonly routeContext?: IFluidHandleContext;\n\n\t/**\n\t * Flag indicating whether or not the entity has services attached.\n\t */\n\treadonly isAttached: boolean;\n\n\t/**\n\t * Runs through the graph and attach the bounded handles.\n\t */\n\tattachGraph(): void;\n\n\tresolveHandle(request: IRequest): Promise<IResponse>;\n}\n\n/**\n * @public\n * @privateRemarks\n * This really should be deprecated and alpha, but since its a merged export with the public interface,\n * it can't have its own docs or different tags.\n */\nexport const IFluidHandle = \"IFluidHandle\";\n\n/**\n * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.\n * @alpha\n */\nexport interface IProvideFluidHandle {\n\t/**\n\t * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.\n\t * @privateRemarks\n\t * This field must be kept so that code from before 2.0.0-rc.4.0.0 (When fluidHandleSymbol was added) still detects handles.\n\t * This is required due to some use-cases mixing package versions.\n\t * More details in packages/runtime/runtime-utils/src/handles.ts and on {@link fluidHandleSymbol}.\n\t */\n\treadonly [IFluidHandle]: IFluidHandleInternal;\n}\n\n/**\n * Handle to a shared {@link FluidObject}.\n * @alpha\n */\nexport interface IFluidHandleInternal<\n\t// REVIEW: Constrain `T` to something? How do we support dds and datastores safely?\n\tout T = unknown, // FluidObject & IFluidLoadable,\n> extends IFluidHandle<T>,\n\t\tIProvideFluidHandle {\n\t/**\n\t * The absolute path to the handle context from the root.\n\t */\n\treadonly absolutePath: string;\n\n\t/**\n\t * Runs through the graph and attach the bounded handles.\n\t */\n\tattachGraph(): void;\n\n\t/**\n\t * Binds the given handle to this one or attach the given handle if this handle is attached.\n\t * A bound handle will also be attached once this handle is attached.\n\t */\n\tbind(handle: IFluidHandleInternal): void;\n}\n\n/**\n * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.\n *\n * @remarks\n * To narrow arbitrary objects to handles do not simply check for this symbol:\n * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility\n * with older implementations of handles that may exist due to dynamic code loading of older packages.\n *\n * @privateRemarks\n * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.\n * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.\n * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:\n * @public\n */\nexport const fluidHandleSymbol: unique symbol = Symbol.for(\n\t\"FluidHandle-3978c7cf-4675-49ba-a20c-bf35efbf43da\",\n);\n\n/**\n * Handle to a shared {@link FluidObject}.\n * @public\n */\nexport interface IFluidHandle<out T = unknown> {\n\t/**\n\t * Flag indicating whether or not the entity has services attached.\n\t */\n\treadonly isAttached: boolean;\n\n\t/**\n\t * Returns a promise to the Fluid Object referenced by the handle.\n\t */\n\tget(): Promise<T>;\n\n\t/**\n\t * Symbol used to mark an object as a {@link (IFluidHandle:interface)}\n\t * and to recover the underlying handle implementation.\n\t *\n\t * @privateRemarks\n\t * Used to recover {@link IFluidHandleInternal}, see {@link toFluidHandleInternal}.\n\t */\n\treadonly [fluidHandleSymbol]: IFluidHandleErased<T>;\n}\n\n/**\n * A type erased Fluid Handle.\n * These can only be produced by the Fluid Framework and provide the implementation details needed to power {@link (IFluidHandle:interface)}.\n * @privateRemarks\n * Created from {@link IFluidHandleInternal} using {@link toFluidHandleErased}.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-interface\nexport interface IFluidHandleErased<T> extends ErasedType<readonly [\"IFluidHandle\", T]> {}\n"]}

package/lib/index.d.ts

@@ -9,8 +9,8 @@ export type { ExtendEventProvider, IErrorEvent, IEvent, IEventProvider, IEventTh
 export type { IProvideFluidLoadable, IProvideFluidRunnable } from "./fluidLoadable.js";
 export { IFluidLoadable, IFluidRunnable } from "./fluidLoadable.js";
 export type { IRequest, IRequestHeader, IResponse } from "./fluidRouter.js";
-export type { IProvideFluidHandleContext, IProvideFluidHandle } from "./handles.js";
-export { IFluidHandleContext, IFluidHandle } from "./handles.js";
+export type { IProvideFluidHandleContext, IProvideFluidHandle, IFluidHandleInternal, IFluidHandleErased, } from "./handles.js";
+export { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from "./handles.js";
 export type { ILoggingError, ITelemetryBaseEvent, ITelemetryBaseLogger, ITelemetryBaseProperties, Tagged, TelemetryBaseEventPropertyType, } from "./logger.js";
 export { LogLevel } from "./logger.js";
 export type { FluidObjectProviderKeys, FluidObject, FluidObjectKeys } from "./provider.js";

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,YAAY,EACX,mBAAmB,EACnB,WAAW,EACX,MAAM,EACN,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,EAC5B,gBAAgB,GAChB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAKpE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5E,YAAY,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjE,YAAY,EACX,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,MAAM,EACN,8BAA8B,GAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,uBAAuB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3F,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,YAAY,EACX,mBAAmB,EACnB,WAAW,EACX,MAAM,EACN,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,EAC5B,gBAAgB,GAChB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAKpE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5E,YAAY,EACX,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEpF,YAAY,EACX,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,MAAM,EACN,8BAA8B,GAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,uBAAuB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3F,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/lib/index.js

@@ -4,6 +4,6 @@
  */
 export { FluidErrorTypes } from "./error.js";
 export { IFluidLoadable, IFluidRunnable } from "./fluidLoadable.js";
-export { IFluidHandleContext, IFluidHandle } from "./handles.js";
+export { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from "./handles.js";
 export { LogLevel } from "./logger.js";
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAc7C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAQpE,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAUjE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport type { IDisposable } from \"./disposable.js\";\n\nexport type { IErrorBase, IGenericError, IUsageError, IThrottlingWarning } from \"./error.js\";\nexport { FluidErrorTypes } from \"./error.js\";\n\nexport type {\n\tExtendEventProvider,\n\tIErrorEvent,\n\tIEvent,\n\tIEventProvider,\n\tIEventThisPlaceHolder,\n\tIEventTransformer,\n\tReplaceIEventThisPlaceHolder,\n\tTransformedEvent,\n} from \"./events.js\";\n\nexport type { IProvideFluidLoadable, IProvideFluidRunnable } from \"./fluidLoadable.js\";\nexport { IFluidLoadable, IFluidRunnable } from \"./fluidLoadable.js\";\n\n// TypeScript forgets the index signature when customers augment IRequestHeader if we export *.\n// So we export the explicit members as a workaround:\n// https://github.com/microsoft/TypeScript/issues/18877#issuecomment-476921038\nexport type { IRequest, IRequestHeader, IResponse } from \"./fluidRouter.js\";\n\nexport type { IProvideFluidHandleContext, IProvideFluidHandle } from \"./handles.js\";\nexport { IFluidHandleContext, IFluidHandle } from \"./handles.js\";\n\nexport type {\n\tILoggingError,\n\tITelemetryBaseEvent,\n\tITelemetryBaseLogger,\n\tITelemetryBaseProperties,\n\tTagged,\n\tTelemetryBaseEventPropertyType,\n} from \"./logger.js\";\nexport { LogLevel } from \"./logger.js\";\nexport type { FluidObjectProviderKeys, FluidObject, FluidObjectKeys } from \"./provider.js\";\nexport type { ConfigTypes, IConfigProviderBase } from \"./config.js\";\nexport type { ISignalEnvelope } from \"./messages.js\";\nexport type { ErasedType } from \"./erasedType.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAc7C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAapE,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAUpF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport type { IDisposable } from \"./disposable.js\";\n\nexport type { IErrorBase, IGenericError, IUsageError, IThrottlingWarning } from \"./error.js\";\nexport { FluidErrorTypes } from \"./error.js\";\n\nexport type {\n\tExtendEventProvider,\n\tIErrorEvent,\n\tIEvent,\n\tIEventProvider,\n\tIEventThisPlaceHolder,\n\tIEventTransformer,\n\tReplaceIEventThisPlaceHolder,\n\tTransformedEvent,\n} from \"./events.js\";\n\nexport type { IProvideFluidLoadable, IProvideFluidRunnable } from \"./fluidLoadable.js\";\nexport { IFluidLoadable, IFluidRunnable } from \"./fluidLoadable.js\";\n\n// TypeScript forgets the index signature when customers augment IRequestHeader if we export *.\n// So we export the explicit members as a workaround:\n// https://github.com/microsoft/TypeScript/issues/18877#issuecomment-476921038\nexport type { IRequest, IRequestHeader, IResponse } from \"./fluidRouter.js\";\n\nexport type {\n\tIProvideFluidHandleContext,\n\tIProvideFluidHandle,\n\tIFluidHandleInternal,\n\tIFluidHandleErased,\n} from \"./handles.js\";\nexport { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from \"./handles.js\";\n\nexport type {\n\tILoggingError,\n\tITelemetryBaseEvent,\n\tITelemetryBaseLogger,\n\tITelemetryBaseProperties,\n\tTagged,\n\tTelemetryBaseEventPropertyType,\n} from \"./logger.js\";\nexport { LogLevel } from \"./logger.js\";\nexport type { FluidObjectProviderKeys, FluidObject, FluidObjectKeys } from \"./provider.js\";\nexport type { ConfigTypes, IConfigProviderBase } from \"./config.js\";\nexport type { ISignalEnvelope } from \"./messages.js\";\nexport type { ErasedType } from \"./erasedType.js\";\n"]}

package/lib/legacy.d.ts

@@ -9,7 +9,7 @@
  */
 
 export {
-	// public APIs
+	// @public APIs
 	ConfigTypes, 
 	ErasedType, 
 	ExtendEventProvider, 
@@ -26,8 +26,8 @@ export {
 	IEventTransformer, 
 	IFluidHandle, 
 	IFluidHandleContext, 
+	IFluidHandleErased, 
 	IFluidLoadable, 
-	IProvideFluidHandle, 
 	IProvideFluidHandleContext, 
 	IProvideFluidLoadable, 
 	IRequest, 
@@ -40,9 +40,13 @@ export {
 	ReplaceIEventThisPlaceHolder, 
 	Tagged, 
 	TelemetryBaseEventPropertyType, 
-	TransformedEvent,
+	TransformedEvent, 
+	fluidHandleSymbol,
  
-	// alpha APIs
+	// @alpha APIs
 	FluidErrorTypes, 
+	IFluidHandleInternal, 
+	ILoggingError, 
+	IProvideFluidHandle, 
 	IThrottlingWarning
 } from "./index.js";

package/lib/logger.d.ts

@@ -81,7 +81,7 @@ export interface ITelemetryErrorEvent extends ITelemetryBaseProperties {
 }
 /**
  * An error object that supports exporting its properties to be logged to telemetry
- * @internal
+ * @alpha
  */
 export interface ILoggingError extends Error {
     /**

package/lib/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiDH;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACvB,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE,EAAE,iBAAiB;CACnB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Property types that can be logged.\n *\n * @remarks Logging entire objects is considered extremely dangerous from a telemetry point of view because people can\n * easily add fields to objects that shouldn't be logged and not realize it's going to be logged.\n * General best practice is to explicitly log the fields you care about from objects.\n * @public\n */\nexport type TelemetryBaseEventPropertyType = string | number | boolean | undefined;\n\n/**\n * A property to be logged to telemetry may require a tag indicating the value may contain sensitive data.\n * This type wraps a value of the given type V in an object along with a string tag (type can be further specified as T).\n *\n * This indicates that the value should be organized or handled differently by loggers in various first or third\n * party scenarios. For example, tags are used to mark data that should not be stored in logs for privacy reasons.\n * @public\n */\nexport interface Tagged<V, T extends string = string> {\n\tvalue: V;\n\ttag: T;\n}\n\n/**\n * JSON-serializable properties, which will be logged with telemetry.\n * @public\n */\nexport interface ITelemetryBaseProperties {\n\t/**\n\t * Properties of a telemetry event. They are string-indexed, and their values restricted to a known set of\n\t * types (optionally \"wrapped\" with {@link Tagged}).\n\t */\n\t[index: string]: TelemetryBaseEventPropertyType | Tagged<TelemetryBaseEventPropertyType>;\n}\n\n/**\n * Base interface for logging telemetry statements.\n * Can contain any number of properties that get serialized as json payload.\n * @param category - category of the event, like \"error\", \"performance\", \"generic\", etc.\n * @param eventName - name of the event.\n * @public\n */\nexport interface ITelemetryBaseEvent extends ITelemetryBaseProperties {\n\tcategory: string;\n\teventName: string;\n}\n\n/**\n * Specify levels of the logs.\n * @public\n */\nexport const LogLevel = {\n\tverbose: 10, // To log any verbose event for example when you are debugging something.\n\tdefault: 20, // Default log level\n\terror: 30, // To log errors.\n} as const;\n\n/**\n * Specify a level to the log to filter out logs based on the level.\n * @public\n */\nexport type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];\n\n/**\n * Interface to output telemetry events.\n * Implemented by hosting app / loader\n * @public\n */\nexport interface ITelemetryBaseLogger {\n\tsend(event: ITelemetryBaseEvent, logLevel?: LogLevel): void;\n\n\tminLogLevel?: LogLevel;\n}\n\n/**\n * Error telemetry event.\n * Maps to category = \"error\"\n *\n * @deprecated For internal use within FluidFramework, use ITelemetryErrorEventExt in \\@fluidframework/telemetry-utils.\n * No replacement intended for FluidFramework consumers.\n * @public\n */\nexport interface ITelemetryErrorEvent extends ITelemetryBaseProperties {\n\teventName: string;\n}\n\n/**\n * An error object that supports exporting its properties to be logged to telemetry\n * @internal\n */\nexport interface ILoggingError extends Error {\n\t/**\n\t * Return all properties from this object that should be logged to telemetry\n\t */\n\tgetTelemetryProperties(): ITelemetryBaseProperties;\n}\n"]}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiDH;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACvB,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE,EAAE,iBAAiB;CACnB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Property types that can be logged.\n *\n * @remarks Logging entire objects is considered extremely dangerous from a telemetry point of view because people can\n * easily add fields to objects that shouldn't be logged and not realize it's going to be logged.\n * General best practice is to explicitly log the fields you care about from objects.\n * @public\n */\nexport type TelemetryBaseEventPropertyType = string | number | boolean | undefined;\n\n/**\n * A property to be logged to telemetry may require a tag indicating the value may contain sensitive data.\n * This type wraps a value of the given type V in an object along with a string tag (type can be further specified as T).\n *\n * This indicates that the value should be organized or handled differently by loggers in various first or third\n * party scenarios. For example, tags are used to mark data that should not be stored in logs for privacy reasons.\n * @public\n */\nexport interface Tagged<V, T extends string = string> {\n\tvalue: V;\n\ttag: T;\n}\n\n/**\n * JSON-serializable properties, which will be logged with telemetry.\n * @public\n */\nexport interface ITelemetryBaseProperties {\n\t/**\n\t * Properties of a telemetry event. They are string-indexed, and their values restricted to a known set of\n\t * types (optionally \"wrapped\" with {@link Tagged}).\n\t */\n\t[index: string]: TelemetryBaseEventPropertyType | Tagged<TelemetryBaseEventPropertyType>;\n}\n\n/**\n * Base interface for logging telemetry statements.\n * Can contain any number of properties that get serialized as json payload.\n * @param category - category of the event, like \"error\", \"performance\", \"generic\", etc.\n * @param eventName - name of the event.\n * @public\n */\nexport interface ITelemetryBaseEvent extends ITelemetryBaseProperties {\n\tcategory: string;\n\teventName: string;\n}\n\n/**\n * Specify levels of the logs.\n * @public\n */\nexport const LogLevel = {\n\tverbose: 10, // To log any verbose event for example when you are debugging something.\n\tdefault: 20, // Default log level\n\terror: 30, // To log errors.\n} as const;\n\n/**\n * Specify a level to the log to filter out logs based on the level.\n * @public\n */\nexport type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];\n\n/**\n * Interface to output telemetry events.\n * Implemented by hosting app / loader\n * @public\n */\nexport interface ITelemetryBaseLogger {\n\tsend(event: ITelemetryBaseEvent, logLevel?: LogLevel): void;\n\n\tminLogLevel?: LogLevel;\n}\n\n/**\n * Error telemetry event.\n * Maps to category = \"error\"\n *\n * @deprecated For internal use within FluidFramework, use ITelemetryErrorEventExt in \\@fluidframework/telemetry-utils.\n * No replacement intended for FluidFramework consumers.\n * @public\n */\nexport interface ITelemetryErrorEvent extends ITelemetryBaseProperties {\n\teventName: string;\n}\n\n/**\n * An error object that supports exporting its properties to be logged to telemetry\n * @alpha\n */\nexport interface ILoggingError extends Error {\n\t/**\n\t * Return all properties from this object that should be logged to telemetry\n\t */\n\tgetTelemetryProperties(): ITelemetryBaseProperties;\n}\n"]}

package/lib/public.d.ts

@@ -9,7 +9,7 @@
  */
 
 export {
-	// public APIs
+	// @public APIs
 	ConfigTypes, 
 	ErasedType, 
 	ExtendEventProvider, 
@@ -26,8 +26,8 @@ export {
 	IEventTransformer, 
 	IFluidHandle, 
 	IFluidHandleContext, 
+	IFluidHandleErased, 
 	IFluidLoadable, 
-	IProvideFluidHandle, 
 	IProvideFluidHandleContext, 
 	IProvideFluidLoadable, 
 	IRequest, 
@@ -40,5 +40,6 @@ export {
 	ReplaceIEventThisPlaceHolder, 
 	Tagged, 
 	TelemetryBaseEventPropertyType, 
-	TransformedEvent
+	TransformedEvent, 
+	fluidHandleSymbol
 } from "./index.js";

package/lib/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.42.3"
+      "packageVersion": "7.43.1"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/core-interfaces",
-  "version": "2.0.0-rc.3.0.3",
+  "version": "2.0.0-rc.4.0.0",
   "description": "Fluid object interfaces",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -49,12 +49,12 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.15.2",
     "@biomejs/biome": "^1.6.2",
-    "@fluid-tools/build-cli": "^0.37.0",
+    "@fluid-tools/build-cli": "^0.38.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.37.0",
-    "@fluidframework/core-interfaces-previous": "npm:@fluidframework/core-interfaces@2.0.0-internal.8.0.0",
+    "@fluidframework/build-tools": "^0.38.0",
+    "@fluidframework/core-interfaces-previous": "npm:@fluidframework/core-interfaces@2.0.0-rc.3.0.0",
     "@fluidframework/eslint-config-fluid": "^5.1.0",
-    "@microsoft/api-extractor": "^7.42.3",
+    "@microsoft/api-extractor": "^7.43.1",
     "@types/node": "^18.19.0",
     "copyfiles": "^2.4.1",
     "eslint": "~8.55.0",
@@ -64,73 +64,24 @@
   },
   "typeValidation": {
     "broken": {
-      "RemovedInterfaceDeclaration_ITelemetryLogger": {
-        "forwardCompat": false,
-        "backCompat": false
+      "RemovedVariableDeclaration_isFluidPackage": {
+        "backCompat": false,
+        "forwardCompat": false
       },
-      "RemovedInterfaceDeclaration_ITelemetryPerformanceEvent": {
+      "InterfaceDeclaration_IFluidHandle": {
         "forwardCompat": false,
         "backCompat": false
       },
-      "RemovedInterfaceDeclaration_ITelemetryGenericEvent": {
-        "forwardCompat": false,
-        "backCompat": false
+      "InterfaceDeclaration_IProvideFluidHandle": {
+        "forwardCompat": false
       },
-      "RemovedInterfaceDeclaration_ITelemetryErrorEvent": {
+      "InterfaceDeclaration_IProvideFluidLoadable": {
         "forwardCompat": false,
         "backCompat": false
       },
-      "RemovedInterfaceDeclaration_ITelemetryProperties": {
+      "InterfaceDeclaration_IFluidLoadable": {
         "forwardCompat": false,
         "backCompat": false
-      },
-      "RemovedTypeAliasDeclaration_TelemetryEventCategory": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedTypeAliasDeclaration_TelemetryEventPropertyType": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedInterfaceDeclaration_ITaggedTelemetryPropertyType": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedInterfaceDeclaration_IFluidCodeDetails": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedVariableDeclaration_IFluidCodeDetailsComparer": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedInterfaceDeclaration_IFluidCodeDetailsComparer": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedInterfaceDeclaration_IFluidCodeDetailsConfig": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedInterfaceDeclaration_IFluidPackage": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedInterfaceDeclaration_IFluidPackageEnvironment": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedInterfaceDeclaration_IProvideFluidCodeDetailsComparer": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedVariableDeclaration_isFluidCodeDetails": {
-        "backCompat": false,
-        "forwardCompat": false
-      },
-      "RemovedVariableDeclaration_isFluidPackage": {
-        "backCompat": false,
-        "forwardCompat": false
       }
     }
   },
@@ -160,9 +111,10 @@
     "format:prettier": "prettier --write . --cache --ignore-path ../../../.prettierignore",
     "lint": "fluid-build . --task lint",
     "lint:fix": "fluid-build . --task eslint:fix --task format",
-    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
-    "tsc:watch": "tsc --watch",
-    "typetests:gen": "fluid-type-test-generator",
+    "place:cjs:package-stub": "copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
+    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && npm run place:cjs:package-stub",
+    "tsc:watch": "npm run place:cjs:package-stub && fluid-tsc commonjs --project ./tsconfig.cjs.json --watch",
+    "typetests:gen": "flub generate typetests --dir . -v --publicFallback",
     "typetests:prepare": "flub typetests --dir . --reset --previous --normalize"
   }
 }

package/src/handles.ts

@@ -3,9 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import type { IFluidLoadable } from "./fluidLoadable.js";
+import { type ErasedType } from "./erasedType.js";
 import type { IRequest, IResponse } from "./fluidRouter.js";
-import type { FluidObject } from "./provider.js";
 
 /**
  * @public
@@ -50,42 +49,80 @@ export interface IFluidHandleContext extends IProvideFluidHandleContext {
 
 /**
  * @public
+ * @privateRemarks
+ * This really should be deprecated and alpha, but since its a merged export with the public interface,
+ * it can't have its own docs or different tags.
  */
-export const IFluidHandle: keyof IProvideFluidHandle = "IFluidHandle";
+export const IFluidHandle = "IFluidHandle";
 
 /**
- * @public
+ * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+ * @alpha
  */
 export interface IProvideFluidHandle {
-	readonly IFluidHandle: IFluidHandle;
+	/**
+	 * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+	 * @privateRemarks
+	 * This field must be kept so that code from before 2.0.0-rc.4.0.0 (When fluidHandleSymbol was added) still detects handles.
+	 * This is required due to some use-cases mixing package versions.
+	 * More details in packages/runtime/runtime-utils/src/handles.ts and on {@link fluidHandleSymbol}.
+	 */
+	readonly [IFluidHandle]: IFluidHandleInternal;
 }
 
 /**
  * Handle to a shared {@link FluidObject}.
- * @public
+ * @alpha
  */
-export interface IFluidHandle<
+export interface IFluidHandleInternal<
 	// REVIEW: Constrain `T` to something? How do we support dds and datastores safely?
-	T = FluidObject & IFluidLoadable,
-> extends IProvideFluidHandle {
+	out T = unknown, // FluidObject & IFluidLoadable,
+> extends IFluidHandle<T>,
+		IProvideFluidHandle {
 	/**
-	 * @deprecated Do not use handle's path for routing. Use `get` to get the underlying object.
-	 *
 	 * The absolute path to the handle context from the root.
 	 */
 	readonly absolutePath: string;
 
 	/**
-	 * Flag indicating whether or not the entity has services attached.
+	 * Runs through the graph and attach the bounded handles.
 	 */
-	readonly isAttached: boolean;
+	attachGraph(): void;
 
 	/**
-	 * @deprecated To be removed. This is part of an internal API surface and should not be called.
-	 *
-	 * Runs through the graph and attach the bounded handles.
+	 * Binds the given handle to this one or attach the given handle if this handle is attached.
+	 * A bound handle will also be attached once this handle is attached.
 	 */
-	attachGraph(): void;
+	bind(handle: IFluidHandleInternal): void;
+}
+
+/**
+ * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
+ *
+ * @remarks
+ * To narrow arbitrary objects to handles do not simply check for this symbol:
+ * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility
+ * with older implementations of handles that may exist due to dynamic code loading of older packages.
+ *
+ * @privateRemarks
+ * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.
+ * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.
+ * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:
+ * @public
+ */
+export const fluidHandleSymbol: unique symbol = Symbol.for(
+	"FluidHandle-3978c7cf-4675-49ba-a20c-bf35efbf43da",
+);
+
+/**
+ * Handle to a shared {@link FluidObject}.
+ * @public
+ */
+export interface IFluidHandle<out T = unknown> {
+	/**
+	 * Flag indicating whether or not the entity has services attached.
+	 */
+	readonly isAttached: boolean;
 
 	/**
 	 * Returns a promise to the Fluid Object referenced by the handle.
@@ -93,10 +130,21 @@ export interface IFluidHandle<
 	get(): Promise<T>;
 
 	/**
-	 * @deprecated To be removed. This is part of an internal API surface and should not be called.
+	 * Symbol used to mark an object as a {@link (IFluidHandle:interface)}
+	 * and to recover the underlying handle implementation.
 	 *
-	 * Binds the given handle to this one or attach the given handle if this handle is attached.
-	 * A bound handle will also be attached once this handle is attached.
+	 * @privateRemarks
+	 * Used to recover {@link IFluidHandleInternal}, see {@link toFluidHandleInternal}.
 	 */
-	bind(handle: IFluidHandle): void;
+	readonly [fluidHandleSymbol]: IFluidHandleErased<T>;
 }
+
+/**
+ * A type erased Fluid Handle.
+ * These can only be produced by the Fluid Framework and provide the implementation details needed to power {@link (IFluidHandle:interface)}.
+ * @privateRemarks
+ * Created from {@link IFluidHandleInternal} using {@link toFluidHandleErased}.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface IFluidHandleErased<T> extends ErasedType<readonly ["IFluidHandle", T]> {}

package/src/index.ts

@@ -27,8 +27,13 @@ export { IFluidLoadable, IFluidRunnable } from "./fluidLoadable.js";
 // https://github.com/microsoft/TypeScript/issues/18877#issuecomment-476921038
 export type { IRequest, IRequestHeader, IResponse } from "./fluidRouter.js";
 
-export type { IProvideFluidHandleContext, IProvideFluidHandle } from "./handles.js";
-export { IFluidHandleContext, IFluidHandle } from "./handles.js";
+export type {
+	IProvideFluidHandleContext,
+	IProvideFluidHandle,
+	IFluidHandleInternal,
+	IFluidHandleErased,
+} from "./handles.js";
+export { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from "./handles.js";
 
 export type {
 	ILoggingError,

package/src/logger.ts

@@ -91,7 +91,7 @@ export interface ITelemetryErrorEvent extends ITelemetryBaseProperties {
 
 /**
  * An error object that supports exporting its properties to be logged to telemetry
- * @internal
+ * @alpha
  */
 export interface ILoggingError extends Error {
 	/**