@fluidframework/container-runtime 2.0.0-dev.7.4.0.217884 → 2.0.0-dev.7.4.0.221926

package/src/containerRuntime.ts

@@ -47,6 +47,7 @@ import {
 	wrapError,
 	ITelemetryLoggerExt,
 	UsageError,
+	LoggingError,
 } from "@fluidframework/telemetry-utils";
 import {
 	DriverHeader,
@@ -87,12 +88,14 @@ import {
 	channelsTreeName,
 	IDataStore,
 	ITelemetryContext,
+} from "@fluidframework/runtime-definitions";
+import type {
 	SerializedIdCompressorWithNoSession,
 	IIdCompressor,
 	IIdCompressorCore,
 	IdCreationRange,
 	SerializedIdCompressorWithOngoingSession,
-} from "@fluidframework/runtime-definitions";
+} from "@fluidframework/id-compressor";
 import {
 	addBlobToSummary,
 	addSummarizeResultToSummary,
@@ -163,7 +166,7 @@ import { formExponentialFn, Throttler } from "./throttler";
 import {
 	GarbageCollector,
 	GCNodeType,
-	gcTombstoneGenerationOptionName,
+	gcGenerationOptionName,
 	IGarbageCollector,
 	IGCRuntimeOptions,
 	IGCStats,
@@ -194,6 +197,7 @@ import {
 	type LocalContainerRuntimeMessage,
 	type OutboundContainerRuntimeMessage,
 	type UnknownContainerRuntimeMessage,
+	ContainerRuntimeGCMessage,
 } from "./messageTypes";
 
 /**
@@ -909,16 +913,18 @@ export class ContainerRuntime
 			metadata?.idCompressorEnabled ?? runtimeOptions.enableRuntimeIdCompressor ?? false;
 		let idCompressor: (IIdCompressor & IIdCompressorCore) | undefined;
 		if (idCompressorEnabled) {
-			const { IdCompressor, createSessionId } = await import("./id-compressor");
+			const { createIdCompressor, deserializeIdCompressor, createSessionId } = await import(
+				"@fluidframework/id-compressor"
+			);
 
 			const pendingLocalState = context.pendingLocalState as IPendingRuntimeState;
 
 			if (pendingLocalState?.pendingIdCompressorState !== undefined) {
-				idCompressor = IdCompressor.deserialize(pendingLocalState.pendingIdCompressorState);
+				idCompressor = deserializeIdCompressor(pendingLocalState.pendingIdCompressorState);
 			} else if (serializedIdCompressor !== undefined) {
-				idCompressor = IdCompressor.deserialize(serializedIdCompressor, createSessionId());
+				idCompressor = deserializeIdCompressor(serializedIdCompressor, createSessionId());
 			} else {
-				idCompressor = IdCompressor.create(logger);
+				idCompressor = createIdCompressor(logger);
 			}
 		}
 
@@ -1341,8 +1347,7 @@ export class ContainerRuntime
 			eventName: "GCFeatureMatrix",
 			metadataValue: JSON.stringify(metadata?.gcFeatureMatrix),
 			inputs: JSON.stringify({
-				gcOptions_gcTombstoneGeneration:
-					this.runtimeOptions.gcOptions[gcTombstoneGenerationOptionName],
+				gcOptions_gcGeneration: this.runtimeOptions.gcOptions[gcGenerationOptionName],
 			}),
 		});
 
@@ -1447,6 +1452,7 @@ export class ContainerRuntime
 			// GC runs in summarizer client and needs access to the real (non-proxy) active information. The proxy
 			// delta manager would always return false for summarizer client.
 			activeConnection: () => this.innerDeltaManager.active,
+			submitMessage: (message: ContainerRuntimeGCMessage) => this.submit(message),
 		});
 
 		const loadedFromSequenceNumber = this.deltaManager.initialSequenceNumber;
@@ -2082,6 +2088,9 @@ export class ContainerRuntime
 				throw new Error("chunkedOp not expected here");
 			case ContainerMessageType.Rejoin:
 				throw new Error("rejoin not expected here");
+			case ContainerMessageType.GC:
+				// GC op is only sent in summarizer which should never have stashed ops.
+				throw new LoggingError("GC op not expected to be stashed in summarizer");
 			default: {
 				// This should be extremely rare for stashed ops.
 				// It would require a newer runtime stashing ops and then an older one applying them,
@@ -2335,6 +2344,9 @@ export class ContainerRuntime
 					this.idCompressor.finalizeCreationRange(messageWithContext.message.contents);
 				}
 				break;
+			case ContainerMessageType.GC:
+				this.garbageCollector.processMessage(messageWithContext.message, local);
+				break;
 			case ContainerMessageType.ChunkedOp:
 			case ContainerMessageType.Rejoin:
 				break;
@@ -2632,18 +2644,28 @@ export class ContainerRuntime
 	}
 
 	private isContainerMessageDirtyable({ type, contents }: OutboundContainerRuntimeMessage) {
-		// For legacy purposes, exclude the old built-in AgentScheduler from dirty consideration as a special-case.
-		// Ultimately we should have no special-cases from the ContainerRuntime's perspective.
-		if (type === ContainerMessageType.Attach) {
-			const attachMessage = contents as InboundAttachMessage;
-			if (attachMessage.id === agentSchedulerId) {
-				return false;
+		// Certain container runtime messages should not mark the container dirty such as the old built-in
+		// AgentScheduler and Garbage collector messages.
+		switch (type) {
+			case ContainerMessageType.Attach: {
+				const attachMessage = contents as InboundAttachMessage;
+				if (attachMessage.id === agentSchedulerId) {
+					return false;
+				}
+				break;
+			}
+			case ContainerMessageType.FluidDataStoreOp: {
+				const envelope = contents;
+				if (envelope.address === agentSchedulerId) {
+					return false;
+				}
+				break;
 			}
-		} else if (type === ContainerMessageType.FluidDataStoreOp) {
-			const envelope = contents;
-			if (envelope.address === agentSchedulerId) {
+			case ContainerMessageType.GC: {
 				return false;
 			}
+			default:
+				break;
 		}
 		return true;
 	}
@@ -2874,7 +2896,7 @@ export class ContainerRuntime
 	 * @param usedRoutes - The routes that are used in all nodes in this Container.
 	 * @see IGarbageCollectionRuntime.updateUsedRoutes
 	 */
-	public updateUsedRoutes(usedRoutes: string[]) {
+	public updateUsedRoutes(usedRoutes: readonly string[]) {
 		// Update our summarizer node's used routes. Updating used routes in summarizer node before
 		// summarizing is required and asserted by the the summarizer node. We are the root and are
 		// always referenced, so the used routes is only self-route (empty string).
@@ -2888,7 +2910,7 @@ export class ContainerRuntime
 	 * This is called to update objects whose routes are unused.
 	 * @param unusedRoutes - Data store and attachment blob routes that are unused in this Container.
 	 */
-	public updateUnusedRoutes(unusedRoutes: string[]) {
+	public updateUnusedRoutes(unusedRoutes: readonly string[]) {
 		const { blobManagerRoutes, dataStoreRoutes } =
 			this.getDataStoreAndBlobManagerRoutes(unusedRoutes);
 		this.blobManager.updateUnusedRoutes(blobManagerRoutes);
@@ -2898,7 +2920,7 @@ export class ContainerRuntime
 	/**
 	 * @deprecated Replaced by deleteSweepReadyNodes.
 	 */
-	public deleteUnusedNodes(unusedRoutes: string[]): string[] {
+	public deleteUnusedNodes(unusedRoutes: readonly string[]): string[] {
 		throw new Error("deleteUnusedRoutes should not be called");
 	}
 
@@ -2907,7 +2929,7 @@ export class ContainerRuntime
 	 * @param sweepReadyRoutes - The routes of nodes that are sweep ready and should be deleted.
 	 * @returns The routes of nodes that were deleted.
 	 */
-	public deleteSweepReadyNodes(sweepReadyRoutes: string[]): string[] {
+	public deleteSweepReadyNodes(sweepReadyRoutes: readonly string[]): readonly string[] {
 		const { dataStoreRoutes, blobManagerRoutes } =
 			this.getDataStoreAndBlobManagerRoutes(sweepReadyRoutes);
 
@@ -2919,7 +2941,7 @@ export class ContainerRuntime
 	 * This is called to update objects that are tombstones.
 	 * @param tombstonedRoutes - Data store and attachment blob routes that are tombstones in this Container.
 	 */
-	public updateTombstonedRoutes(tombstonedRoutes: string[]) {
+	public updateTombstonedRoutes(tombstonedRoutes: readonly string[]) {
 		const { blobManagerRoutes, dataStoreRoutes } =
 			this.getDataStoreAndBlobManagerRoutes(tombstonedRoutes);
 		this.blobManager.updateTombstonedRoutes(blobManagerRoutes);
@@ -2979,7 +3001,7 @@ export class ContainerRuntime
 	 * @returns Two route lists - One that contains routes for blob manager and another one that contains routes
 	 * for data stores.
 	 */
-	private getDataStoreAndBlobManagerRoutes(routes: string[]) {
+	private getDataStoreAndBlobManagerRoutes(routes: readonly string[]) {
 		const blobManagerRoutes: string[] = [];
 		const dataStoreRoutes: string[] = [];
 		for (const route of routes) {
@@ -3056,10 +3078,10 @@ export class ContainerRuntime
 			);
 		}
 
-		// If there are pending (unacked ops), the summary will not be eventual consistent and it may even be
-		// incorrect. So, wait for the container to be saved with a timeout. If the container is not saved
-		// within the timeout, check if it should be failed or can continue.
-		if (this.validateSummaryBeforeUpload && this.hasPendingMessages()) {
+		// If the container is dirty, i.e., there are pending unacked ops, the summary will not be eventual consistent
+		// and it may even be incorrect. So, wait for the container to be saved with a timeout. If the container is not
+		// saved within the timeout, check if it should be failed or can continue.
+		if (this.validateSummaryBeforeUpload && this.isDirty) {
 			const countBefore = this.pendingMessagesCount;
 			// The timeout for waiting for pending ops can be overridden via configurations.
 			const pendingOpsTimeout =
@@ -3081,7 +3103,7 @@ export class ContainerRuntime
 			// happens, whether we attempted to wait for these ops to be acked and what was the result.
 			summaryNumberLogger.sendTelemetryEvent({
 				eventName: "PendingOpsWhileSummarizing",
-				saved: this.hasPendingMessages() ? false : true,
+				saved: !this.isDirty,
 				timeout: pendingOpsTimeout,
 				countBefore,
 				countAfter: this.pendingMessagesCount,
@@ -3360,7 +3382,7 @@ export class ContainerRuntime
 	}
 
 	/**
-	 * This helper is called during summarization. If there are pending ops, it will return a failed summarize result
+	 * This helper is called during summarization. If the container is dirty, it will return a failed summarize result
 	 * (IBaseSummarizeResult) unless this is the final summarize attempt and SkipFailingIncorrectSummary option is set.
 	 * @param logger - The logger to be used for sending telemetry.
 	 * @param referenceSequenceNumber - The reference sequence number of the summary attempt.
@@ -3376,7 +3398,7 @@ export class ContainerRuntime
 		finalAttempt: boolean,
 		beforeSummaryGeneration: boolean,
 	): Promise<IBaseSummarizeResult | undefined> {
-		if (!this.hasPendingMessages()) {
+		if (!this.isDirty) {
 			return;
 		}
 
@@ -3724,6 +3746,7 @@ export class ContainerRuntime
 	/**
 	 * Finds the right store and asks it to resubmit the message. This typically happens when we
 	 * reconnect and there are pending messages.
+	 * ! Note: successfully resubmitting an op that has been successfully sequenced is not possible due to checks in the ConnectionStateHandler (Loader layer)
 	 * @param message - The original LocalContainerRuntimeMessage.
 	 * @param localOpMetadata - The local metadata associated with the original message.
 	 */
@@ -3752,6 +3775,9 @@ export class ContainerRuntime
 			case ContainerMessageType.Rejoin:
 				this.submit(message);
 				break;
+			case ContainerMessageType.GC:
+				// GC op is only sent in summarizer which should never reconnect.
+				throw new LoggingError("GC op not expected to be resubmitted in summarizer");
 			default: {
 				// This case should be very rare - it would imply an op was stashed from a
 				// future version of runtime code and now is being applied on an older version

package/src/dataStores.ts

@@ -61,13 +61,8 @@ import {
 } from "./dataStoreContext";
 import { StorageServiceWithAttachBlobs } from "./storageServiceWithAttachBlobs";
 import { IDataStoreAliasMessage, isDataStoreAliasMessage } from "./dataStore";
-import { GCNodeType, disableDatastoreSweepKey, sendGCUnexpectedUsageEvent } from "./gc";
-import {
-	summarizerClientType,
-	IContainerRuntimeMetadata,
-	nonDataStorePaths,
-	rootHasIsolatedChannels,
-} from "./summary";
+import { GCNodeType, disableDatastoreSweepKey } from "./gc";
+import { IContainerRuntimeMetadata, nonDataStorePaths, rootHasIsolatedChannels } from "./summary";
 
 type PendingAliasResolve = (success: boolean) => void;
 
@@ -281,6 +276,19 @@ export class DataStores implements IDisposable {
 		}
 
 		const context = this.contexts.get(aliasMessage.internalId);
+		// If the data store has been deleted, log an error and ignore this message. This helps prevent document
+		// corruption in case a deleted data store accidentally submitted a signal.
+		if (
+			this.checkAndLogIfDeleted(
+				aliasMessage.internalId,
+				context,
+				"Changed",
+				"processAliasMessageCore",
+			)
+		) {
+			return false;
+		}
+
 		if (context === undefined) {
 			this.mc.logger.sendErrorEvent({
 				eventName: "AliasFluidDataStoreNotFound",
@@ -382,18 +390,43 @@ export class DataStores implements IDisposable {
 
 	public resubmitDataStoreOp(envelope: IEnvelope, localOpMetadata: unknown) {
 		const context = this.contexts.get(envelope.address);
+		// If the data store has been deleted, log an error and throw an error. If there are local changes for a
+		// deleted data store, it can otherwise lead to inconsistent state when compared to other clients.
+		if (
+			this.checkAndLogIfDeleted(envelope.address, context, "Changed", "resubmitDataStoreOp")
+		) {
+			throw new DataCorruptionError("Context is deleted!", {
+				callSite: "resubmitDataStoreOp",
+				...tagCodeArtifacts({ id: envelope.address }),
+			});
+		}
 		assert(!!context, 0x160 /* "There should be a store context for the op" */);
 		context.reSubmit(envelope.contents, localOpMetadata);
 	}
 
 	public rollbackDataStoreOp(envelope: IEnvelope, localOpMetadata: unknown) {
 		const context = this.contexts.get(envelope.address);
+		// If the data store has been deleted, log an error and throw an error. If there are local changes for a
+		// deleted data store, it can otherwise lead to inconsistent state when compared to other clients.
+		if (
+			this.checkAndLogIfDeleted(envelope.address, context, "Changed", "rollbackDataStoreOp")
+		) {
+			throw new DataCorruptionError("Context is deleted!", {
+				callSite: "rollbackDataStoreOp",
+				...tagCodeArtifacts({ id: envelope.address }),
+			});
+		}
 		assert(!!context, 0x2e8 /* "There should be a store context for the op" */);
 		context.rollback(envelope.contents, localOpMetadata);
 	}
 
 	public async applyStashedOp(envelope: IEnvelope): Promise<unknown> {
 		const context = this.contexts.get(envelope.address);
+		// If the data store has been deleted, log an error and ignore this message. This helps prevent document
+		// corruption in case the data store that stashed the op is deleted.
+		if (this.checkAndLogIfDeleted(envelope.address, context, "Changed", "applyStashedOp")) {
+			return undefined;
+		}
 		assert(!!context, 0x161 /* "There should be a store context for the op" */);
 		return context.applyStashedOp(envelope.contents);
 	}
@@ -411,8 +444,21 @@ export class DataStores implements IDisposable {
 	) {
 		const envelope = message.contents as IEnvelope;
 		const transformed = { ...message, contents: envelope.contents };
-		this.validateNotDeleted(envelope.address);
 		const context = this.contexts.get(envelope.address);
+
+		// If the data store has been deleted, log an error and ignore this message. This helps prevent document
+		// corruption in case a deleted data store accidentally submitted an op.
+		if (
+			this.checkAndLogIfDeleted(
+				envelope.address,
+				context,
+				"Changed",
+				"processFluidDataStoreOp",
+			)
+		) {
+			return;
+		}
+
 		assert(!!context, 0x162 /* "There should be a store context for the op" */);
 		context.process(transformed, local, localMessageMetadata);
 
@@ -430,7 +476,22 @@ export class DataStores implements IDisposable {
 		requestHeaderData: RuntimeHeaderData,
 	): Promise<FluidDataStoreContext> {
 		const headerData = { ...defaultRuntimeHeaderData, ...requestHeaderData };
-		this.validateNotDeleted(id, headerData);
+		if (
+			this.checkAndLogIfDeleted(
+				id,
+				this.contexts.get(id),
+				"Requested",
+				"getDataStore",
+				requestHeaderData,
+			)
+		) {
+			// The requested data store has been deleted by gc. Create a 404 response exception.
+			const request: IRequest = { url: id };
+			throw responseToException(
+				createResponseError(404, "DataStore was deleted", request),
+				request,
+			);
+		}
 
 		const context = await this.contexts.getBoundOrRemoted(id, headerData.wait);
 		if (context === undefined) {
@@ -448,8 +509,16 @@ export class DataStores implements IDisposable {
 		id: string,
 		requestHeaderData: RuntimeHeaderData,
 	): Promise<FluidDataStoreContext | undefined> {
-		// If the data store has been deleted, return undefined.
-		if (this.checkIfDeleted(id, requestHeaderData)) {
+		// If the data store has been deleted, log an error and return undefined.
+		if (
+			this.checkAndLogIfDeleted(
+				id,
+				this.contexts.get(id),
+				"Requested",
+				"getDataStoreIfAvailable",
+				requestHeaderData,
+			)
+		) {
 			return undefined;
 		}
 		const headerData = { ...defaultRuntimeHeaderData, ...requestHeaderData };
@@ -461,55 +530,43 @@ export class DataStores implements IDisposable {
 	}
 
 	/**
-	 * Checks if the data store has been deleted by GC.
-	 * @param id - data store id
-	 * @param request - the request information to log if the validation detects the data store has been deleted
-	 * @param requestHeaderData - the request header information to log if the validation detects the data store has been deleted
+	 * Checks if the data store has been deleted by GC. If so, log an error.
+	 * @param id - The data store's id.
+	 * @param context - The data store context.
+	 * @param callSite - The function name this is called from.
+	 * @param requestHeaderData - The request header information to log if the data store is deleted.
 	 * @returns true if the data store is deleted. Otherwise, returns false.
 	 */
-	private checkIfDeleted(id: string, requestHeaderData?: RuntimeHeaderData) {
+	private checkAndLogIfDeleted(
+		id: string,
+		context: FluidDataStoreContext | undefined,
+		deletedLogSuffix: string,
+		callSite: string,
+		requestHeaderData?: RuntimeHeaderData,
+	) {
 		const dataStoreNodePath = `/${id}`;
 		if (!this.isDataStoreDeleted(dataStoreNodePath)) {
 			return false;
 		}
-		assert(
-			!this.contexts.has(id),
-			0x570 /* Inconsistent state! GC says the data store is deleted, but the data store is not deleted from the runtime. */,
-		);
-		sendGCUnexpectedUsageEvent(
-			this.mc,
-			{
-				eventName: "GC_Deleted_DataStore_Requested",
-				category: "error",
-				isSummarizerClient: this.runtime.clientDetails.type === summarizerClientType,
-				id,
-				headers: JSON.stringify(requestHeaderData),
-				gcTombstoneEnforcementAllowed: this.runtime.gcTombstoneEnforcementAllowed,
-			},
-			undefined /* packagePath */,
-		);
-		return true;
-	}
 
-	/**
-	 * Validate that the data store had not been deleted by GC.
-	 * @param id - data store id
-	 * @param requestHeaderData - the request header information to log if the validation detects the data store has been deleted
-	 */
-	private validateNotDeleted(id: string, requestHeaderData?: RuntimeHeaderData) {
-		if (this.checkIfDeleted(id, requestHeaderData)) {
-			// The requested data store is removed by gc. Create a 404 gc response exception.
-			const request: IRequest = { url: id };
-			throw responseToException(
-				createResponseError(404, "DataStore was deleted", request),
-				request,
-			);
-		}
+		this.mc.logger.sendErrorEvent({
+			eventName: `GC_Deleted_DataStore_${deletedLogSuffix}`,
+			...tagCodeArtifacts({ id }),
+			callSite,
+			headers: JSON.stringify(requestHeaderData),
+			exists: context !== undefined,
+		});
+		return true;
 	}
 
 	public processSignal(fluidDataStoreId: string, message: IInboundSignalMessage, local: boolean) {
-		this.validateNotDeleted(fluidDataStoreId);
 		const context = this.contexts.get(fluidDataStoreId);
+		// If the data store has been deleted, log an error and ignore this message. This helps prevent document
+		// corruption in case a deleted data store accidentally submitted a signal.
+		if (this.checkAndLogIfDeleted(fluidDataStoreId, context, "Changed", "processSignal")) {
+			return;
+		}
+
 		if (!context) {
 			// Attach message may not have been processed yet
 			assert(!local, 0x163 /* "Missing datastore for local signal" */);
@@ -711,7 +768,7 @@ export class DataStores implements IDisposable {
 	 * After GC has run, called to notify this Container's data stores of routes that are used in it.
 	 * @param usedRoutes - The routes that are used in all data stores in this Container.
 	 */
-	public updateUsedRoutes(usedRoutes: string[]) {
+	public updateUsedRoutes(usedRoutes: readonly string[]) {
 		// Get a map of data store ids to routes used in it.
 		const usedDataStoreRoutes = unpackChildNodesUsedRoutes(usedRoutes);
 
@@ -733,7 +790,7 @@ export class DataStores implements IDisposable {
 	 * This is called to update objects whose routes are unused. The unused objects are deleted.
 	 * @param unusedRoutes - The routes that are unused in all data stores in this Container.
 	 */
-	public updateUnusedRoutes(unusedRoutes: string[]) {
+	public updateUnusedRoutes(unusedRoutes: readonly string[]) {
 		for (const route of unusedRoutes) {
 			const pathParts = route.split("/");
 			// Delete data store only if its route (/datastoreId) is in unusedRoutes. We don't want to delete a data
@@ -756,7 +813,7 @@ export class DataStores implements IDisposable {
 	 * be deleted.
 	 * @returns The routes of data stores and its objects that were deleted.
 	 */
-	public deleteSweepReadyNodes(sweepReadyDataStoreRoutes: string[]): string[] {
+	public deleteSweepReadyNodes(sweepReadyDataStoreRoutes: readonly string[]): readonly string[] {
 		// If sweep for data stores is not enabled, return empty list indicating nothing is deleted.
 		if (this.mc.config.getBoolean(disableDatastoreSweepKey) === true) {
 			return [];
@@ -765,23 +822,25 @@ export class DataStores implements IDisposable {
 			const pathParts = route.split("/");
 			const dataStoreId = pathParts[1];
 
-			// TODO: GC:Validation - Skip any routes already deleted
 			// Ignore sub-data store routes because a data store and its sub-routes are deleted together, so, we only
 			// need to delete the data store.
 			if (pathParts.length > 2) {
 				continue;
 			}
 
-			if (!this.contexts.has(dataStoreId)) {
+			const dataStoreContext = this.contexts.get(dataStoreId);
+			if (dataStoreContext === undefined) {
 				this.mc.logger.sendErrorEvent({
 					eventName: "DeletedDataStoreNotFound",
-					dataStoreId,
+					...tagCodeArtifacts({ id: dataStoreId }),
+					details: {
+						alreadyDeleted: this.isDataStoreDeleted(dataStoreId),
+					},
 				});
+				continue;
 			}
 
-			const dataStore = this.contexts.get(dataStoreId);
-			assert(dataStore !== undefined, 0x571 /* Attempting to delete unknown dataStore */);
-			dataStore.delete();
+			dataStoreContext.delete();
 
 			// Delete the contexts of sweep ready data stores.
 			this.contexts.delete(dataStoreId);
@@ -796,7 +855,7 @@ export class DataStores implements IDisposable {
 	 * scenarios with accessing deleted content without actually deleting content from summaries.
 	 * @param tombstonedRoutes - The routes that are tombstones in all data stores in this Container.
 	 */
-	public updateTombstonedRoutes(tombstonedRoutes: string[]) {
+	public updateTombstonedRoutes(tombstonedRoutes: readonly string[]) {
 		const tombstonedDataStoresSet: Set<string> = new Set();
 		for (const route of tombstonedRoutes) {
 			const pathParts = route.split("/");

package/src/gc/garbageCollection.md

@@ -50,16 +50,19 @@ Mark phase is enabled by default for a container. It is enabled during creation
 
 ### Sweep phase
 
-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.
+In this phase, the GC algorithm deletes any Fluid object that has been unreferenced for a sufficient time to guarantee
+they could never be referenced again by any active clients, i.e., clients that have the object in memory and could reference it again.
+The Fluid Runtime enforces a maximum session length (configurable) in order to guarantee all in-memory objects are cleared before
+it concludes an object is safe to delete.
 
-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.
+GC sweep phase runs in two stages:
 
-Tombstone is intended for use by early adopters of GC and is documented in more detail [here](./gcEarlyAdoption.md).
+-   The first stage is the "Tombstone" stage, where objects are marked as Tombstones, meaning GC believes they will
+    never be referenced again and are safe to delete. They are not yet deleted at this point, but any attempt to
+    load them will fail. This way, there's a chance to recover a Tombstoned object in case we detect it's still being used.
+-   The second stage is the "Sweep" or "Delete" stage, where the objects are fully deleted.
+    This occurs after a configurable delay called the "Sweep Grace Period", to give time for application teams
+    to monitor for Tombstone-related errors and react before delete occurs.
 
 ## GC Configuration
 
@@ -67,7 +70,8 @@ The default configuration for GC today is:
 
 -   GC Mark Phase is **enabled**, including Tombstone Mode
 -   Session Expiry is **enabled**
--   GC Sweep Phase is **disabled**
+-   The "Tombstone" stage of Sweep Phase is **enabled** (attempting to load a tombstoned object will fail)
+-   The "Delete" stage of Sweep Phase is **disabled**
     -   Note: Once enabled, Sweep will only run for documents created from that point forward
 
 ### Techniques used for configuration
@@ -94,12 +98,7 @@ covered in the [Advanced Configuration](./gcEarlyAdoption.md#more-advanced-confi
 
 ### 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).
+To enable the Sweep Phase for new documents, you must set the `enableGCSweep` GC Option to true.
 
 ### More Advanced Configuration