@fluidframework/container-runtime 2.0.0-dev.5.3.2.178189 → 2.0.0-dev.6.4.0.191457

package/src/deltaScheduler.ts

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryLoggerExt, TelemetryLogger } from "@fluidframework/telemetry-utils";
-import { performance } from "@fluidframework/common-utils";
+import { ITelemetryLoggerExt, formatTick } from "@fluidframework/telemetry-utils";
+import { performance } from "@fluid-internal/client-utils";
 import { IDeltaManager } from "@fluidframework/container-definitions";
 import { IDocumentMessage, ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
 
@@ -111,20 +111,16 @@ export class DeltaScheduler {
 					if (this.schedulingLog) {
 						this.logger.sendTelemetryEvent({
 							eventName: "InboundOpsPartialProcessingTime",
-							duration: TelemetryLogger.formatTick(elapsedTime),
+							duration: formatTick(elapsedTime),
 							opsProcessed:
 								this.schedulingLog.lastSequenceNumber -
 								this.schedulingLog.firstSequenceNumber +
 								1,
 							opsRemainingToProcess: this.deltaManager.inbound.length,
-							processingTime: TelemetryLogger.formatTick(
-								this.schedulingLog.totalProcessingTime,
-							),
+							processingTime: formatTick(this.schedulingLog.totalProcessingTime),
 							numberOfTurns: this.schedulingLog.numberOfTurns,
 							batchesProcessed: this.schedulingLog.numberOfBatchesProcessed,
-							timeToResume: TelemetryLogger.formatTick(
-								performance.now() - currentTime,
-							),
+							timeToResume: formatTick(performance.now() - currentTime),
 						});
 					}
 					this.deltaManager.inbound.resume();
@@ -147,13 +143,13 @@ export class DeltaScheduler {
 				eventName: "InboundOpsProcessingTime",
 				opsRemainingToProcess: this.schedulingLog.opsRemainingToProcess,
 				numberOfTurns: this.schedulingLog.numberOfTurns,
-				processingTime: TelemetryLogger.formatTick(this.schedulingLog.totalProcessingTime),
+				processingTime: formatTick(this.schedulingLog.totalProcessingTime),
 				opsProcessed:
 					this.schedulingLog.lastSequenceNumber -
 					this.schedulingLog.firstSequenceNumber +
 					1,
 				batchesProcessed: this.schedulingLog.numberOfBatchesProcessed,
-				duration: TelemetryLogger.formatTick(currentTime - this.schedulingLog.startTime),
+				duration: formatTick(currentTime - this.schedulingLog.startTime),
 				schedulingCount: this.schedulingCount,
 			});
 

package/src/error.ts

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ContainerErrorTypes } from "@fluidframework/container-definitions";
+import { IFluidErrorBase, LoggingError } from "@fluidframework/telemetry-utils";
+
+/**
+ * Error indicating that a client's session has reached its time limit and is closed.
+ */
+export class ClientSessionExpiredError extends LoggingError implements IFluidErrorBase {
+	readonly errorType = ContainerErrorTypes.clientSessionExpiredError;
+
+	constructor(message: string, readonly expiryMs: number) {
+		super(message, { timeoutMs: expiryMs });
+	}
+}

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

@@ -3,10 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { Timer } from "@fluidframework/common-utils";
-import { LazyPromise } from "@fluidframework/core-utils";
-import { ClientSessionExpiredError, DataProcessingError } from "@fluidframework/container-utils";
-import { IRequestHeader } from "@fluidframework/core-interfaces";
+import { LazyPromise, Timer } from "@fluidframework/core-utils";
+import { IRequest, IRequestHeader } from "@fluidframework/core-interfaces";
 import {
 	gcTreeKey,
 	IGarbageCollectionData,
@@ -14,17 +12,23 @@ import {
 	ISummarizeResult,
 	ITelemetryContext,
 } from "@fluidframework/runtime-definitions";
-import { ReadAndParseBlob } from "@fluidframework/runtime-utils";
+import { createResponseError, responseToException } from "@fluidframework/runtime-utils";
 import {
-	ChildLogger,
+	createChildLogger,
+	createChildMonitoringContext,
+	DataProcessingError,
 	ITelemetryLoggerExt,
-	loggerToMonitoringContext,
 	MonitoringContext,
 	PerformanceEvent,
 } from "@fluidframework/telemetry-utils";
 
-import { RuntimeHeaders } from "../containerRuntime";
-import { RefreshSummaryResult } from "../summary";
+import {
+	AllowInactiveRequestHeaderKey,
+	InactiveResponseHeaderKey,
+	RuntimeHeaders,
+} from "../containerRuntime";
+import { ClientSessionExpiredError } from "../error";
+import { IRefreshSummaryResult } from "../summary";
 import { generateGCConfigs } from "./gcConfigs";
 import {
 	GCNodeType,
@@ -137,11 +141,13 @@ export class GarbageCollector implements IGarbageCollector {
 		const baseSnapshot = createParams.baseSnapshot;
 		const readAndParseBlob = createParams.readAndParseBlob;
 
-		this.mc = loggerToMonitoringContext(
-			ChildLogger.create(createParams.baseLogger, "GarbageCollector", {
+		this.mc = createChildMonitoringContext({
+			logger: createParams.baseLogger,
+			namespace: "GarbageCollector",
+			properties: {
 				all: { completedGCRuns: () => this.completedRuns },
-			}),
-		);
+			},
+		});
 
 		this.configs = generateGCConfigs(this.mc, createParams);
 
@@ -466,8 +472,11 @@ export class GarbageCollector implements IGarbageCollector {
 		});
 
 		const logger = options.logger
-			? ChildLogger.create(options.logger, undefined, {
-					all: { completedGCRuns: () => this.completedRuns },
+			? createChildLogger({
+					logger: options.logger,
+					properties: {
+						all: { completedGCRuns: () => this.completedRuns },
+					},
 			  })
 			: this.mc.logger;
 
@@ -570,14 +579,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,
@@ -636,7 +648,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,
@@ -715,7 +727,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,
@@ -833,45 +845,15 @@ export class GarbageCollector implements IGarbageCollector {
 	}
 
 	/**
-	 * Called to refresh the latest summary state. This happens when either a pending summary is acked or a snapshot
-	 * is downloaded and should be used to update the state.
+	 * Called to refresh the latest summary state. This happens when either a pending summary is acked.
 	 */
-	public async refreshLatestSummary(
-		proposalHandle: string | undefined,
-		result: RefreshSummaryResult,
-		readAndParseBlob: ReadAndParseBlob,
-	): Promise<void> {
-		const latestSnapshotData = await this.summaryStateTracker.refreshLatestSummary(
-			proposalHandle,
-			result,
-			readAndParseBlob,
-		);
-
-		// If the latest summary was updated but it was not tracked by this client, our state needs to be updated from
-		// this snapshot data.
-		if (this.shouldRunGC && result.latestSummaryUpdated && !result.wasSummaryTracked) {
-			// The current reference timestamp should be available if we are refreshing state from a snapshot. There has
-			// to be at least one op (summary op / ack, if nothing else) if a snapshot was taken.
-			const currentReferenceTimestampMs = this.runtime.getCurrentReferenceTimestampMs();
-			if (currentReferenceTimestampMs === undefined) {
-				throw DataProcessingError.create(
-					"No reference timestamp when updating GC state from snapshot",
-					"refreshLatestSummary",
-					undefined,
-					{
-						proposalHandle,
-						summaryRefSeq: result.summaryRefSeq,
-						gcConfigs: JSON.stringify(this.configs),
-					},
-				);
-			}
-			this.updateStateFromSnapshotData(latestSnapshotData, currentReferenceTimestampMs);
-		}
+	public async refreshLatestSummary(result: IRefreshSummaryResult): Promise<void> {
+		return this.summaryStateTracker.refreshLatestSummary(result);
 	}
 
 	/**
 	 * Called when a node with the given id is updated. If the node is inactive, log an error.
-	 * @param nodePath - The id of the node that changed.
+	 * @param nodePath - The path of the node that changed.
 	 * @param reason - Whether the node was loaded or changed.
 	 * @param timestampMs - The timestamp when the node changed.
 	 * @param packagePath - The package path of the node. This may not be available if the node hasn't been loaded yet.
@@ -888,6 +870,7 @@ export class GarbageCollector implements IGarbageCollector {
 			return;
 		}
 
+		// This will log if appropriate
 		this.telemetryTracker.nodeUsed({
 			id: nodePath,
 			usageType: reason,
@@ -899,6 +882,29 @@ export class GarbageCollector implements IGarbageCollector {
 			lastSummaryTime: this.getLastSummaryTimestampMs(),
 			viaHandle: requestHeaders?.[RuntimeHeaders.viaHandle],
 		});
+
+		// Unless this is a Loaded event, we're done after telemetry tracking
+		if (reason !== "Loaded") {
+			return;
+		}
+
+		// We may throw when loading an Inactive object, depending on these preconditions
+		const shouldThrowOnInactiveLoad =
+			!this.isSummarizerClient &&
+			this.configs.throwOnInactiveLoad === true &&
+			requestHeaders?.[AllowInactiveRequestHeaderKey] !== true;
+		const state = this.unreferencedNodesState.get(nodePath)?.state;
+
+		if (shouldThrowOnInactiveLoad && state === "Inactive") {
+			const request: IRequest = { url: nodePath };
+			const error = responseToException(
+				createResponseError(404, "Object is inactive", request, {
+					[InactiveResponseHeaderKey]: true,
+				}),
+				request,
+			);
+			throw error;
+		}
 	}
 
 	/**

package/src/gc/gcConfigs.ts

@@ -3,8 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { UsageError } from "@fluidframework/container-utils";
-import { MonitoringContext } from "@fluidframework/telemetry-utils";
+import { MonitoringContext, UsageError } from "@fluidframework/telemetry-utils";
 import { IContainerRuntimeMetadata } from "../summary";
 import {
 	currentGCVersion,
@@ -153,6 +152,8 @@ export function generateGCConfigs(
 		throw new UsageError("inactive timeout should not be greater than the sweep timeout");
 	}
 
+	const throwOnInactiveLoad: boolean | undefined = createParams.gcOptions.throwOnInactiveLoad;
+
 	// Whether we are running in test mode. In this mode, unreferenced nodes are immediately deleted.
 	const testMode =
 		mc.config.getBoolean(gcTestModeKey) ?? createParams.gcOptions.runGCInTestMode === true;
@@ -172,6 +173,7 @@ export function generateGCConfigs(
 		sessionExpiryTimeoutMs,
 		sweepTimeoutMs,
 		inactiveTimeoutMs,
+		throwOnInactiveLoad,
 		persistedGcFeatureMatrix,
 		gcVersionInBaseSnapshot,
 		gcVersionInEffect,

package/src/gc/gcDefinitions.ts

@@ -17,7 +17,7 @@ import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
 import {
 	IContainerRuntimeMetadata,
 	ICreateContainerMetadata,
-	RefreshSummaryResult,
+	IRefreshSummaryResult,
 } from "../summary";
 
 export type GCVersion = number;
@@ -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 gcVersionUpgradeToV3Key = "Fluid.GarbageCollection.GCVersionUpgradeToV3";
-// 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;
@@ -228,11 +227,7 @@ export interface IGarbageCollector {
 	/** Returns the GC details generated from the base snapshot. */
 	getBaseGCDetails(): Promise<IGarbageCollectionDetailsBase>;
 	/** Called when the latest summary of the system has been refreshed. */
-	refreshLatestSummary(
-		proposalHandle: string | undefined,
-		result: RefreshSummaryResult,
-		readAndParseBlob: ReadAndParseBlob,
-	): Promise<void>;
+	refreshLatestSummary(result: IRefreshSummaryResult): Promise<void>;
 	/** Called when a node is updated. Used to detect and log when an inactive node is changed or loaded. */
 	nodeUpdated(
 		nodePath: string,
@@ -349,6 +344,8 @@ export interface IGarbageCollectorConfigs {
 	readonly sweepTimeoutMs: number | undefined;
 	/** The time after which an unreferenced node is inactive. */
 	readonly inactiveTimeoutMs: number;
+	/** It is easier for users to diagnose InactiveObject usage if we throw on load, which this option enables */
+	readonly throwOnInactiveLoad: boolean | undefined;
 	/** Tracks whether GC should run in test mode. In this mode, unreferenced objects are deleted immediately. */
 	readonly testMode: boolean;
 	/**

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/common-utils";
+import { assert } from "@fluidframework/core-utils";
 import { ISnapshotTree } from "@fluidframework/protocol-definitions";
 import {
 	gcBlobPrefix,
@@ -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,13 +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.
- */
-export function tagAsCodeArtifact(value: string) {
-	return {
-		value,
-		tag: TelemetryDataTag.CodeArtifact,
-	};
-}