@fluidframework/container-runtime 2.0.0-internal.6.3.3 → 2.0.0-internal.6.4.0

package/src/dataStoreContext.ts

@@ -314,7 +314,9 @@ export abstract class FluidDataStoreContext
 			properties: {
 				all: tagCodeArtifacts({
 					fluidDataStoreId: this.id,
-					fullPackageName: this.pkg?.join("/"),
+					// The package name is a getter because `this.pkg` may not be initialized during construction.
+					// For data stores loaded from summary, it is initialized during data store realization.
+					fullPackageName: () => this.pkg?.join("/"),
 				}),
 			},
 		});

package/src/dataStores.ts

@@ -67,7 +67,7 @@ import { StorageServiceWithAttachBlobs } from "./storageServiceWithAttachBlobs";
 import { IDataStoreAliasMessage, isDataStoreAliasMessage } from "./dataStore";
 import {
 	GCNodeType,
-	sweepDatastoresKey,
+	disableDatastoreSweepKey,
 	throwOnTombstoneLoadKey,
 	sendGCUnexpectedUsageEvent,
 } from "./gc";
@@ -212,7 +212,7 @@ export class DataStores implements IDisposable {
 
 	public async waitIfPendingAlias(maybeAlias: string): Promise<AliasResult> {
 		const pendingAliasPromise = this.pendingAliases.get(maybeAlias);
-		return pendingAliasPromise === undefined ? "Success" : pendingAliasPromise;
+		return pendingAliasPromise ?? "Success";
 	}
 
 	public processAttachMessage(message: ISequencedDocumentMessage, local: boolean) {
@@ -820,11 +820,11 @@ export class DataStores implements IDisposable {
 	 * Delete data stores and its objects that are sweep ready.
 	 * @param sweepReadyDataStoreRoutes - The routes of data stores and its objects that are sweep ready and should
 	 * be deleted.
-	 * @returns - The routes of data stores and its objects that were deleted.
+	 * @returns The routes of data stores and its objects that were deleted.
 	 */
 	public deleteSweepReadyNodes(sweepReadyDataStoreRoutes: string[]): string[] {
 		// If sweep for data stores is not enabled, return empty list indicating nothing is deleted.
-		if (this.mc.config.getBoolean(sweepDatastoresKey) !== true) {
+		if (this.mc.config.getBoolean(disableDatastoreSweepKey) === true) {
 			return [];
 		}
 		for (const route of sweepReadyDataStoreRoutes) {

package/src/gc/garbageCollection.md

@@ -48,12 +48,60 @@ In this phase, the GC algorithm identifies all Fluid objects that are unreferenc
 
 Mark phase is enabled by default for a container. It is enabled during creation of the container runtime and remains enabled throughout its lifetime. Basically, this setting is persisted in the summary and cannot be changed.
 
-If you wish to disable this, set the `gcAllowed` option to `false` in `IGCRuntimeOptions`. These options are under `IContainerRuntimeOptions` and are passed to the container runtime during its creation. Note that this will disable GC permanently (including the sweep phase) for the container during its lifetime.
+### Sweep phase
 
-See `IGCRuntimeOptions` in [containerRuntime.ts](../containerRuntime.ts) for more options to control GC behavior.
+In this phase, the GC algorithm identifies all Fluid objects that have been unreferenced for a specific amount of time (typically 30-40 days) and deletes them.
+Objects are only swept once the GC system is sure that they could never be referenced again by any active clients, i.e., clients that have the object in memory and could reference it.
+The Fluid Runtime enforces a maximum session length (configurable) in order to guarantee an object is safe to delete after sufficient time has elapsed.
 
-### Sweep phase
+GC sweep phase has not been enabled by default yet. A "soft" version of Sweep called "Tombstone Mode" is enabled by default
+as part of the Mark Phase when Sweep is disabled. In this mode, any object that GC determines is ready to be deleted is
+marked as a "Tombstone", which triggers certain logging events and/or behavior changes if/when that Tombstoned object is
+accessed by the application.
+
+Tombstone is intended for use by early adopters of GC and is documented in more detail [here](./gcEarlyAdoption.md).
+
+## GC Configuration
+
+The default configuration for GC today is:
+
+-   GC Mark Phase is **enabled**, including Tombstone Mode
+-   Session Expiry is **enabled**
+-   GC Sweep Phase is **disabled**
+    -   Note: Once enabled, Sweep will only run for documents created from that point forward
+
+### Techniques used for configuration
+
+There are two ways to configure the Fluid Framework's GC behavior, referred to by name throughout these documents:
+
+1.  **"GC Options"**: `ContainerRuntime.loadRuntime` takes an options value of type `IContainerRuntimeOptions`.
+    This type includes a sub-object `gcOptions`, for GC-specific options.
+2.  **"Config Settings"**: The `Loader`'s constructor takes in `ILoaderProps`, which includes `configProvider?: IConfigProviderBase`
+    This configProvider can be used to inject config settings.
+
+Typically GC Options are used for more "official" and stable configuration, whereas Config Settings provide a mechanism
+for apps to override settings easily, e.g. by backing their `IConfigProviderBase` with a configuration/flighting service.
+In cases where a behavior is controlled by both a Config Setting and GC Option, you may experiment at first using Config Settings
+and then later update the passed-in GC Options to finalize the configuration in your code.
+
+### Disabling Mark Phase
+
+If you wish to disable Mark Phase for newly-created documents, set the `gcAllowed` GC Option to `false`.
+Note that this will disable GC permanently (including the sweep phase) for the container during its lifetime.
+
+Mark Phase can also be disabled just for the session, among other behaviors,
+covered in the [Advanced Configuration](./gcEarlyAdoption.md#more-advanced-configurations) docs.
+
+### Enabling Sweep Phase
+
+To enable Sweep Phase for new documents, you must set the `gcSweepGeneration` GC Option to a number, e.g. 0 to start.
+The full semantics of this GC Option are discussed [here](./gcEarlyAdoption.md#more-about-gcsweepgeneration-and-gctombstonegeneration).
+Note that this will disabled Tombstone Mode.
+
+A full treatment of Tombstone and Sweep configuration can be found in
+[this companion document geared towards early adopters of GC](./gcEarlyAdoption.md).
 
-In this phase, the GC algorithm identifies all Fluid objects that have been unreferenced for a specific amount of time (typically 30-40 days) and deletes them. Objects are only swept once the GC system is sure that they could never be referenced again by any active clients, i.e., clients that have the object in memory and could reference it.
+### More Advanced Configuration
 
-GC sweep phase has not been enabled yet. More details will be added here when sweep is enabled.
+For additional behaviors that can be configured (e.g. for testing), please see these
+[Advanced Configuration](./gcEarlyAdoption.md#more-advanced-configurations) docs.

package/src/gc/garbageCollection.ts

@@ -577,14 +577,17 @@ export class GarbageCollector implements IGarbageCollector {
 
 	/**
 	 * Runs the GC Mark phase. It does the following:
+	 *
 	 * 1. Marks all referenced nodes in this run by clearing tracking for them.
+	 *
 	 * 2. Marks unreferenced nodes in this run by starting tracking for them.
+	 *
 	 * 3. Calls the runtime to update nodes that were marked referenced.
 	 *
 	 * @param gcResult - The result of the GC run on the gcData.
 	 * @param allReferencedNodeIds - Nodes referenced in this GC run + referenced between previous and current GC run.
 	 * @param currentReferenceTimestampMs - The timestamp to be used for unreferenced nodes' timestamp.
-	 * @returns - A list of sweep ready nodes, i.e., nodes that ready to be deleted.
+	 * @returns A list of sweep ready nodes, i.e., nodes that ready to be deleted.
 	 */
 	private runMarkPhase(
 		gcResult: IGCResult,
@@ -643,7 +646,7 @@ export class GarbageCollector implements IGarbageCollector {
 	 * @param sweepReadyNodes - List of nodes that are sweep ready.
 	 * @param currentReferenceTimestampMs - The timestamp to be used for unreferenced nodes' timestamp.
 	 * @param logger - The logger to be used to log any telemetry.
-	 * @returns - A list of nodes that have been deleted.
+	 * @returns A list of nodes that have been deleted.
 	 */
 	private runSweepPhase(
 		gcResult: IGCResult,
@@ -722,7 +725,7 @@ export class GarbageCollector implements IGarbageCollector {
 	 * This function identifies nodes that were referenced since the last run.
 	 * If these nodes are currently unreferenced, they will be assigned new unreferenced state by the current run.
 	 *
-	 * @returns - a list of all nodes referenced from the last local summary until now.
+	 * @returns A list of all nodes referenced from the last local summary until now.
 	 */
 	private findAllNodesReferencedBetweenGCs(
 		currentGCData: IGarbageCollectionData,

package/src/gc/gcDefinitions.ts

@@ -43,29 +43,28 @@ export const gcTombstoneGenerationOptionName = "gcTombstoneGeneration";
  */
 export const gcSweepGenerationOptionName = "gcSweepGeneration";
 
-// Feature gate key to turn GC on / off.
+/** Config key to turn GC on / off. */
 export const runGCKey = "Fluid.GarbageCollection.RunGC";
-// Feature gate key to turn GC sweep on / off.
+/** Config key to turn GC sweep on / off. */
 export const runSweepKey = "Fluid.GarbageCollection.RunSweep";
-// Feature gate key to turn GC test mode on / off.
+/** Config key to turn GC test mode on / off. */
 export const gcTestModeKey = "Fluid.GarbageCollection.GCTestMode";
-// Feature gate key to expire a session after a set period of time.
+/** Config key to expire a session after a set period of time. Defaults to true. */
 export const runSessionExpiryKey = "Fluid.GarbageCollection.RunSessionExpiry";
-// Feature gate key to turn GC sweep log off.
+/** Config key to turn GC sweep log off. */
 export const disableSweepLogKey = "Fluid.GarbageCollection.DisableSweepLog";
-// Feature gate key to disable the tombstone feature, i.e., tombstone information is not read / written into summary.
+/** Config key to disable the tombstone feature, i.e., tombstone information is not read / written into summary. */
 export const disableTombstoneKey = "Fluid.GarbageCollection.DisableTombstone";
-// Feature gate to enable throwing an error when tombstone object is loaded (requested).
+/** Config key to enable throwing an error when tombstone object is loaded (requested). */
 export const throwOnTombstoneLoadKey = "Fluid.GarbageCollection.ThrowOnTombstoneLoad";
-// Feature gate to enable throwing an error when tombstone object is used (e.g. outgoing or incoming ops).
+/** Config key to enable throwing an error when tombstone object is used (e.g. outgoing or incoming ops). */
 export const throwOnTombstoneUsageKey = "Fluid.GarbageCollection.ThrowOnTombstoneUsage";
-// Feature gate to enable GC version upgrade.
+/** Config key to enable GC version upgrade. */
 export const gcVersionUpgradeToV4Key = "Fluid.GarbageCollection.GCVersionUpgradeToV4";
-// Feature gate to enable GC sweep for datastores.
-// TODO: Remove Test from the flag when we are confident to turn on sweep
-export const sweepDatastoresKey = "Fluid.GarbageCollection.Test.SweepDataStores";
-// Feature gate to enable GC sweep for attachment blobs.
-export const sweepAttachmentBlobsKey = "Fluid.GarbageCollection.Test.SweepAttachmentBlobs";
+/** Config key to disable GC sweep for datastores. */
+export const disableDatastoreSweepKey = "Fluid.GarbageCollection.DisableDataStoreSweep";
+/** Config key to disable GC sweep for attachment blobs. */
+export const disableAttachmentBlobSweepKey = "Fluid.GarbageCollection.DisableAttachmentBlobSweep";
 
 // One day in milliseconds.
 export const oneDayMs = 1 * 24 * 60 * 60 * 1000;

package/src/gc/gcEarlyAdoption.md

@@ -0,0 +1,145 @@
+# Garbage Collection: Advanced configuration for early adopters
+
+_For a technical overview of Garbage Collection, start with [GarbageCollection.md](./garbageCollection.md)_
+
+GC Sweep is not yet enabled by default, and until that time early adopters have several configuration options available
+for how to enable GC and monitor for any GC-impacting bugs that would need to be mitigated.
+
+Please refer to the section [Techniques Used for Configuration](./garbageCollection.md#techniques-used-for-configuration)
+before continuing, to ensure you're familiar with using "GC Options" and "Config Settings" for configuring GC.
+
+## What's on by default
+
+GC Mark Phase is enabled by default, which includes marking objects that are ready to be deleted as Tombstones.
+FF will log an informational event if/when a Tombstoned object is loaded - a scenario that would represent data loss if Sweep were enabled.
+The eventName for the Tombstone log ends with `GC_Tombstone_DataStore_Requested`.
+
+There's a similar event logged long before an object is Tombstoned. Ater only 7 days (configurable), an unreferenced object is considered
+"Inactive", and FF will log if an Inactive object is loaded as well.
+The eventName for the Inactive log ends with `InactiveObject_Loaded`.
+
+## Getting earlier signals: Shortening the InactiveObject timeout
+
+The default timeout for an unreferenced object to become "Inactive" is 7 days. This is intended to be long enough such that
+it's very unlikely to hit a legitimate case where an object is revived within the same session it was deleted (e.g. delete then undo).
+Based on your application's user experience, you may choose to shorten this timeout to get an earlier signal (but beware of false positives).
+
+To override the default InactiveObject timeout, use the `inactiveTimeoutMs` GC Option.
+There's also a Config Setting which can be used for testing (if the Config Provider allows overriding via localStorage/sessionStorage):
+`Fluid.GarbageCollection.TestOverride.InactiveTimeoutMs`
+
+## Enabling Tombstone Enforcement
+
+By default, GC is marking objects as Tombstoned, but merely logging if they're used after that point.
+You can enable enforcement of Tombstone objects to simulate real Sweep while having the peace of mind
+that the data is not yet deleted from the user's file, and can be recovered.
+
+The first step is to prevent the Fluid Framework from loading a Tombstoned object (via `handle.get()` as described previously),
+by using this Config Setting:
+
+```ts
+"Fluid.GarbageCollection.ThrowOnTombstoneLoad": true
+```
+
+Now, even with `Fluid.GarbageCollection.ThrowOnTombstoneLoad` set to true, changes to a Tombstoned object will be allowed.
+This is required for the advanced recovery options to work, explained [below](#advanced-back-door-recovering-and-reviving-tombstoned-objects).
+
+To instruct FF to treat Tombstoned objects as if they are truly not present in the document, use this Config Setting:
+
+```ts
+"Fluid.GarbageCollection.ThrowOnTombstoneUsage": true
+```
+
+### In case of emergency: Bumping the gcTombstoneGeneration
+
+GC includes a mechanism for Tombstone by which all new documents may be stamped with a "Generation" number,
+and if set then Tombstone is only enforceable for documents of the latest Generation. This number is specified
+via the `gcTombstoneGeneration` GC Option, and will not change over the lifetime of a given document.
+
+In case a bug is released that is found to cause GC errors, a bump to the gcTombstoneGeneration can be incuded
+with the fix, which will prevent any user pain for those potentially affected documents that were exposed to the bug.
+
+If gcTombstoneGeneration is unset, Tombstone enforcement will be enabled/disabled as otherwise configured.
+In other words, until you start using this, Tombstone enforcement will apply to all documents.
+
+### Advanced "Back door": Recovering and reviving Tombstoned objects
+
+If your application has Tombstone enabled and your users are encountering Tombstones - even at the point where
+Tombstone enforcement is enabled - there is a way to still access these objects to recover them and property
+reference them ("revival"). However, please understand that this is an advanced and unsupported path that may
+be immediately deprecated at any time.
+
+As mentioned above, bumping the gcTombstoneGeneration will free up impacted documents, but that's a permanent
+mitigation - those documents will never be exposed to GC Tombstone or Sweep.
+
+If there's a particular codepath in your application where objects being loaded may be Tombstoned,
+you may use this advanced "back door" to recover them and then properly reference them, thus restoring the document.
+For this to work, you must disable the `Fluid.GarbageCollection.ThrowOnTombstoneUsage` Config Setting.
+
+When a Tombstoned object (via `handle.get()`) fails to load, the 404 response error object has an `underlyingResponseHeaders` with the
+`isTombstoned` flag set to true: i.e. `error.underlyingResponseHeaders?.isTombstoned === true`. In this case,
+you may turn around and use `IContainerRuntime.resolveHandle` with `allowTombstone: true` in `IRequest.headers` to request
+the object again - this time it will succeed.
+
+To be very clear once again - This path uses deprecated APIs (`resolveHandle`) and comes with no guarantees of support.
+
+### Tombstones and the Summarizer Client
+
+Note: The Summarizer client will _never_ throw on usage or load of a Tombstoned object.
+
+## Enabling Sweep
+
+To enable Sweep for the first time, set this GC Option:
+
+```ts
+gcSweepGeneration: 0;
+```
+
+This will enable sweep for all documents moving forward _as well as_ any documents created with `gcTombstoneGeneration: 0`
+(this is a special case in the code).
+
+### A caveat...
+
+If you used `gcTombstoneGeneration` **and ever bumped it**, you should skip 0 here to avoid enabling Sweep for old / at-risk documents:
+
+```ts
+gcSweepGeneration: 1;
+```
+
+Remember, you can always bump `gcSweepGeneration` to disable Sweep for all existing documents and start fresh,
+in case a major bug is discovered and fixed.
+
+### More about gcSweepGeneration and gcTombstoneGeneration
+
+`gcSweepGeneration` is persisted and immutable in the document, just like `gcTombstoneGeneration`.
+However, behavior differs in a few important ways.
+
+For Tombstone, if `gcTombstoneGeneration` is not set, Tombstone enforcement will be **enabled**.
+For Sweep however, if `gcSweepGeneration` is not set, Sweep enforcement will be **disabled**.
+
+This means that until the `gcSweepGeneration` GC Option is set, _no existing document will be eligible for Sweep, ever_.
+So all documents created since the most recent bump to the gcSweepGeneration will have Sweep enabled.
+Note that if `gcSweepGeneration` is set and matches, Tombstone Mode is off for the session and `gcTombstoneGeneration` is ignored.
+
+And as mentioned above, there is a special case when `gcSweepGeneration === 0`: Any document with `gcTombstoneGeneration: 0` will
+be eligible for Sweep as well. This was done for historical reasons due to circumstances during GC's development.
+
+## More Advanced Configurations
+
+There are a handful of other configuration options/settings that can be used to tweak GC's behavior,
+mostly for testing. Please refer to the function [`generateGCConfigs` in gcConfigs.ts](./gcConfigs.ts) and the
+[setting/option names listed in gcDefinitions.ts](./gcDefinitions.ts) for the full story.
+
+Examples of available advanced configuration include:
+
+-   Disabling GC permanently for new files
+-   Overriding GC Mark/Sweep enablement for this session:
+    -   Disabling running GC Mark and/or Sweep phases for this session
+    -   Forcing GC Mark and/or Sweep to run for this session even if otherwise it would be disabled
+    -   Disabling Tombstone Mode (don't even mark objects as Tombstones)
+    -   Disabling the deletion of either DataStores or AttachmentBlobs independent of one another (when Sweep is enabled)
+-   Overriding the default Session Expiry for new files (or disabling it altogether, which will also disable Tombstone/Sweep)
+-   Overriding the Sweep Timeout, _independent of Session Expiry_, so use with care (for testing purposes only - data loss could occur)
+-   Running in "Test Mode", where objects are deleted as soon as they're unreferenced
+-   Force "Full GC" to run, which ignores incremental optimizations based on previously computed GC Data
+-   Treat InactiveObjects like Tombstones: throw an error on load (with the same back door to follow-up with a successful request)

package/src/gc/gcHelpers.ts

@@ -12,7 +12,6 @@ import {
 	IGarbageCollectionData,
 	IGarbageCollectionDetailsBase,
 } from "@fluidframework/runtime-definitions";
-import { TelemetryDataTag } from "@fluidframework/telemetry-utils";
 import { GCFeatureMatrix, GCVersion, IGCMetadata } from "./gcDefinitions";
 import {
 	IGarbageCollectionNodeData,
@@ -304,14 +303,3 @@ export function unpackChildNodesGCDetails(gcDetails: IGarbageCollectionDetailsBa
 export function trimLeadingAndTrailingSlashes(str: string) {
 	return str.replace(/^\/+|\/+$/g, "");
 }
-
-/**
- * Tags the passed value as a CodeArtifact and returns the tagged value.
- * @deprecated - Use telemetry-utils tagCodeArtifacts instead
- */
-export function tagAsCodeArtifact(value: string) {
-	return {
-		value,
-		tag: TelemetryDataTag.CodeArtifact,
-	};
-}

package/src/gc/gcTelemetry.ts

@@ -23,8 +23,6 @@ import {
 	runSweepKey,
 } from "./gcDefinitions";
 import { UnreferencedStateTracker } from "./gcUnreferencedStateTracker";
-// eslint-disable-next-line import/no-deprecated
-import { tagAsCodeArtifact } from "./gcHelpers";
 
 type NodeUsageType = "Changed" | "Loaded" | "Revived";
 
@@ -184,8 +182,7 @@ export class GCTelemetryTracker {
 				{
 					eventName: `GC_Tombstone_${nodeType}_Revived`,
 					category: "generic",
-					// eslint-disable-next-line import/no-deprecated
-					url: tagAsCodeArtifact(id),
+					...tagCodeArtifacts({ url: id }),
 					gcTombstoneEnforcementAllowed: this.gcTombstoneEnforcementAllowed,
 				},
 				undefined /* packagePath */,

package/src/gc/index.ts

@@ -29,8 +29,8 @@ export {
 	runSessionExpiryKey,
 	runSweepKey,
 	stableGCVersion,
-	sweepAttachmentBlobsKey,
-	sweepDatastoresKey,
+	disableAttachmentBlobSweepKey,
+	disableDatastoreSweepKey,
 	throwOnTombstoneLoadKey,
 	throwOnTombstoneUsageKey,
 	UnreferencedState,
@@ -42,7 +42,6 @@ export {
 	shouldAllowGcSweep,
 	trimLeadingAndTrailingSlashes,
 	unpackChildNodesGCDetails,
-	tagAsCodeArtifact,
 } from "./gcHelpers";
 export { runGarbageCollection } from "./gcReferenceGraphAlgorithm";
 export {

package/src/index.ts

@@ -4,10 +4,6 @@
  */
 
 export {
-	ContainerMessageType,
-	ContainerRuntimeMessage,
-	IContainerRuntimeMessageCompatDetails,
-	CompatModeBehavior,
 	ISummaryRuntimeOptions,
 	ISummaryBaseConfiguration,
 	ISummaryConfigurationHeuristics,
@@ -28,6 +24,13 @@ export {
 	ICompressionRuntimeOptions,
 	CompressionAlgorithms,
 } from "./containerRuntime";
+export {
+	ContainerMessageType,
+	ContainerRuntimeMessage,
+	IContainerRuntimeMessageCompatDetails,
+	CompatModeBehavior,
+	RecentlyAddedContainerRuntimeMessageDetails,
+} from "./messageTypes";
 export { FluidDataStoreRegistry } from "./dataStoreRegistry";
 export { IGCRuntimeOptions, IGCStats } from "./gc";
 export {

package/src/messageTypes.ts

@@ -0,0 +1,225 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+import {
+	IEnvelope,
+	InboundAttachMessage,
+	IAttachMessage,
+	IdCreationRangeWithStashedState,
+	IdCreationRange,
+} from "@fluidframework/runtime-definitions";
+import { IDataStoreAliasMessage } from "./dataStore";
+import { IChunkedOp } from "./opLifecycle";
+
+export enum ContainerMessageType {
+	// An op to be delivered to store
+	FluidDataStoreOp = "component",
+
+	// Creates a new store
+	Attach = "attach",
+
+	// Chunked operation.
+	ChunkedOp = "chunkedOp",
+
+	// Signifies that a blob has been attached and should not be garbage collected by storage
+	BlobAttach = "blobAttach",
+
+	// Ties our new clientId to our old one on reconnect
+	Rejoin = "rejoin",
+
+	// Sets the alias of a root data store
+	Alias = "alias",
+
+	/**
+	 * An op containing an IdRange of Ids allocated using the runtime's IdCompressor since
+	 * the last allocation op was sent.
+	 * See the [IdCompressor README](./id-compressor/README.md) for more details.
+	 */
+	IdAllocation = "idAllocation",
+}
+
+/**
+ * How should an older client handle an unrecognized remote op type?
+ *
+ * @internal
+ */
+export type CompatModeBehavior =
+	/** Ignore the op. It won't be persisted if this client summarizes */
+	| "Ignore"
+	/** Fail processing immediately. (The container will close) */
+	| "FailToProcess";
+
+/**
+ * All the info an older client would need to know how to handle an unrecognized remote op type
+ *
+ * @internal
+ */
+export interface IContainerRuntimeMessageCompatDetails {
+	/** How should an older client handle an unrecognized remote op type? */
+	behavior: CompatModeBehavior;
+}
+
+/**
+ * The unpacked runtime message / details to be handled or dispatched by the ContainerRuntime.
+ * Message type are differentiated via a `type` string and contain different contents depending on their type.
+ *
+ * IMPORTANT: when creating one to be serialized, set the properties in the order they appear here.
+ * This way stringified values can be compared.
+ */
+interface TypedContainerRuntimeMessage<TType extends ContainerMessageType, TContents> {
+	/** Type of the op, within the ContainerRuntime's domain */
+	type: TType;
+	/** Domain-specific contents, interpreted according to the type */
+	contents: TContents;
+}
+
+/**
+ * Additional details expected for any recently added message.
+ * @internal
+ */
+export interface RecentlyAddedContainerRuntimeMessageDetails {
+	/** Info describing how to handle this op in case the type is unrecognized (default: fail to process) */
+	compatDetails: IContainerRuntimeMessageCompatDetails;
+}
+
+export type ContainerRuntimeDataStoreOpMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.FluidDataStoreOp,
+	IEnvelope
+>;
+export type InboundContainerRuntimeAttachMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.Attach,
+	InboundAttachMessage
+>;
+export type OutboundContainerRuntimeAttachMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.Attach,
+	IAttachMessage
+>;
+export type ContainerRuntimeChunkedOpMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.ChunkedOp,
+	IChunkedOp
+>;
+export type ContainerRuntimeBlobAttachMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.BlobAttach,
+	undefined
+>;
+export type ContainerRuntimeRejoinMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.Rejoin,
+	undefined
+>;
+export type ContainerRuntimeAliasMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.Alias,
+	IDataStoreAliasMessage
+>;
+export type LocalContainerRuntimeIdAllocationMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.IdAllocation,
+	IdCreationRangeWithStashedState
+>;
+export type ContainerRuntimeIdAllocationMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.IdAllocation,
+	IdCreationRange & { stashedState?: never }
+>;
+
+/**
+ * Represents an unrecognized {@link TypedContainerRuntimeMessage}, e.g. a message from a future version of the container runtime.
+ * @internal
+ */
+export interface UnknownContainerRuntimeMessage
+	extends Partial<RecentlyAddedContainerRuntimeMessageDetails> {
+	/** Invalid type of the op, within the ContainerRuntime's domain. This value should never exist at runtime.
+	 * This is useful for type narrowing but should never be used as an actual message type at runtime.
+	 * Actual value will not be "__unknown...", but the type `Exclude<string, ContainerMessageType>` is not supported.
+	 */
+	type: "__unknown_container_message_type__never_use_as_value__";
+
+	/** Domain-specific contents, but not decipherable by an unknown op. */
+	contents: unknown;
+}
+
+/**
+ * A {@link TypedContainerRuntimeMessage} that is received from the server and will be processed by the container runtime.
+ */
+export type InboundContainerRuntimeMessage =
+	| ContainerRuntimeDataStoreOpMessage
+	| InboundContainerRuntimeAttachMessage
+	| ContainerRuntimeChunkedOpMessage
+	| ContainerRuntimeBlobAttachMessage
+	| ContainerRuntimeRejoinMessage
+	| ContainerRuntimeAliasMessage
+	| ContainerRuntimeIdAllocationMessage
+	// Inbound messages may include unknown types from other clients, so we include that as a special case here
+	| UnknownContainerRuntimeMessage;
+
+/** A {@link TypedContainerRuntimeMessage} that has been generated by the container runtime but is not yet being sent to the server. */
+export type LocalContainerRuntimeMessage =
+	| ContainerRuntimeDataStoreOpMessage
+	| OutboundContainerRuntimeAttachMessage
+	| ContainerRuntimeChunkedOpMessage
+	| ContainerRuntimeBlobAttachMessage
+	| ContainerRuntimeRejoinMessage
+	| ContainerRuntimeAliasMessage
+	| LocalContainerRuntimeIdAllocationMessage
+	// In rare cases (e.g. related to stashed ops) we could have a local message of an unknown type
+	| UnknownContainerRuntimeMessage;
+
+/** A {@link TypedContainerRuntimeMessage} that is being sent to the server from the container runtime. */
+export type OutboundContainerRuntimeMessage =
+	| ContainerRuntimeDataStoreOpMessage
+	| OutboundContainerRuntimeAttachMessage
+	| ContainerRuntimeChunkedOpMessage
+	| ContainerRuntimeBlobAttachMessage
+	| ContainerRuntimeRejoinMessage
+	| ContainerRuntimeAliasMessage
+	| ContainerRuntimeIdAllocationMessage;
+
+/**
+ * An unpacked ISequencedDocumentMessage with the inner TypedContainerRuntimeMessage type/contents/etc
+ * promoted up to the outer object
+ */
+export type InboundSequencedContainerRuntimeMessage = Omit<
+	ISequencedDocumentMessage,
+	"type" | "contents"
+> &
+	InboundContainerRuntimeMessage;
+
+/** Essentially ISequencedDocumentMessage except that `type` is not `string` to enable narrowing
+ * as `Exclude<string, InboundContainerRuntimeMessage['type']>` is not supported.
+ * There should never be a runtime value of "__not_a_...".
+ * Currently additionally replaces `contents` type until protocol-definitions update is taken with `unknown` instead of `any`.
+ */
+type InboundSequencedNonContainerRuntimeMessage = Omit<
+	ISequencedDocumentMessage,
+	"type" | "contents"
+> & { type: "__not_a_container_runtime_message_type__"; contents: unknown };
+
+export type InboundSequencedContainerRuntimeMessageOrSystemMessage =
+	| InboundSequencedContainerRuntimeMessage
+	| InboundSequencedNonContainerRuntimeMessage;
+
+/** A [loose] InboundSequencedContainerRuntimeMessage that is recent and may contain compat details.
+ * It exists solely to to provide access to those details.
+ */
+export type InboundSequencedRecentlyAddedContainerRuntimeMessage = ISequencedDocumentMessage &
+	Partial<RecentlyAddedContainerRuntimeMessageDetails>;
+
+/**
+ * The unpacked runtime message / details to be handled or dispatched by the ContainerRuntime
+ *
+ * IMPORTANT: when creating one to be serialized, set the properties in the order they appear here.
+ * This way stringified values can be compared.
+ *
+ * @deprecated - this is an internal type which should not be used outside of the package.
+ * Internally, it is superseded by `TypedContainerRuntimeMessage`.
+ *
+ * @internal
+ */
+export interface ContainerRuntimeMessage {
+	/** Type of the op, within the ContainerRuntime's domain */
+	type: ContainerMessageType;
+	/** Domain-specific contents, interpreted according to the type */
+	contents: any;
+	/** Info describing how to handle this op in case the type is unrecognized (default: fail to process) */
+	compatDetails?: IContainerRuntimeMessageCompatDetails;
+}