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

package/src/gc/garbageCollection.ts

@@ -21,13 +21,13 @@ import {
 	MonitoringContext,
 	PerformanceEvent,
 } from "@fluidframework/telemetry-utils";
-
 import {
 	InactiveResponseHeaderKey,
 	RuntimeHeaderData,
 	TombstoneResponseHeaderKey,
 } from "../containerRuntime";
 import { ClientSessionExpiredError } from "../error";
+import { ContainerMessageType, ContainerRuntimeGCMessage } from "../messageTypes";
 import { IRefreshSummaryResult } from "../summary";
 import { generateGCConfigs } from "./gcConfigs";
 import {
@@ -42,8 +42,15 @@ import {
 	IGarbageCollectorConfigs,
 	IMarkPhaseStats,
 	ISweepPhaseStats,
+	GarbageCollectionMessage,
+	GarbageCollectionMessageType,
 } from "./gcDefinitions";
-import { cloneGCData, concatGarbageCollectionData, getGCDataFromSnapshot } from "./gcHelpers";
+import {
+	cloneGCData,
+	compatBehaviorAllowsGCMessageType,
+	concatGarbageCollectionData,
+	getGCDataFromSnapshot,
+} from "./gcHelpers";
 import { runGarbageCollection } from "./gcReferenceGraphAlgorithm";
 import { IGarbageCollectionSnapshotData, IGarbageCollectionState } from "./gcSummaryDefinitions";
 import { GCSummaryStateTracker } from "./gcSummaryStateTracker";
@@ -117,7 +124,7 @@ export class GarbageCollector implements IGarbageCollector {
 
 	/** If false, loading or using a Tombstoned object should merely log, not fail */
 	public get tombstoneEnforcementAllowed(): boolean {
-		return this.configs.tombstoneEnforcementAllowed;
+		return this.configs.sweepEnabled;
 	}
 	/** If true, throw an error when a tombstone data store is retrieved */
 	public get throwOnTombstoneLoad(): boolean {
@@ -137,6 +144,8 @@ export class GarbageCollector implements IGarbageCollector {
 	/** Returns true if connection is active, i.e. it's "write" connection and the runtime is connected. */
 	private readonly activeConnection: () => boolean;
 
+	private readonly submitMessage: (message: ContainerRuntimeGCMessage) => void;
+
 	public get summaryStateNeedsReset(): boolean {
 		return this.summaryStateTracker.doesSummaryStateNeedReset;
 	}
@@ -152,6 +161,7 @@ export class GarbageCollector implements IGarbageCollector {
 		this.getNodePackagePath = createParams.getNodePackagePath;
 		this.getLastSummaryTimestampMs = createParams.getLastSummaryTimestampMs;
 		this.activeConnection = createParams.activeConnection;
+		this.submitMessage = createParams.submitMessage;
 
 		const baseSnapshot = createParams.baseSnapshot;
 		const readAndParseBlob = createParams.readAndParseBlob;
@@ -247,7 +257,7 @@ export class GarbageCollector implements IGarbageCollector {
 		/**
 		 * Set up the initializer which initializes the GC state from the data in base snapshot. This is done when
 		 * connected in write mode or when GC runs the first time. It sets up all unreferenced nodes from the base
-		 * GC state and updates their inactive or sweep ready state.
+		 * GC state and updates their inactive or sweep-ready state.
 		 */
 		this.initializeGCStateFromBaseSnapshotP = new LazyPromise<void>(async () => {
 			/**
@@ -418,6 +428,7 @@ export class GarbageCollector implements IGarbageCollector {
 						this.configs.inactiveTimeoutMs,
 						currentReferenceTimestampMs,
 						this.configs.sweepTimeoutMs,
+						this.configs.sweepGracePeriodMs,
 					),
 				);
 			}
@@ -428,7 +439,7 @@ export class GarbageCollector implements IGarbageCollector {
 
 	/**
 	 * Called when the connection state of the runtime changes, i.e., it connects or disconnects. GC subscribes to this
-	 * to initialize the base state for non-summarizer clients so that they can track inactive / sweep ready nodes.
+	 * to initialize the base state for non-summarizer clients so that they can track inactive / sweep-ready nodes.
 	 * @param connected - Whether the runtime connected / disconnected.
 	 * @param clientId - The clientId of this runtime.
 	 */
@@ -444,7 +455,7 @@ export class GarbageCollector implements IGarbageCollector {
 		 * the receiving summarizer client.
 		 *
 		 * Ideally, this initialization should only be done for summarizer client. However, we are currently rolling out
-		 * sweep in phases and we want to track when inactive and sweep ready objects are used in any client.
+		 * sweep in phases and we want to track when inactive and sweep-ready objects are used in any client.
 		 */
 		if (this.activeConnection() && this.configs.shouldRunGC) {
 			this.initializeGCStateFromBaseSnapshotP.catch((error) => {});
@@ -547,10 +558,15 @@ export class GarbageCollector implements IGarbageCollector {
 
 	/**
 	 * Runs garbage collection. It does the following:
+	 *
 	 * 1. It generates / analyzes the runtime's reference graph.
+	 *
 	 * 2. Generates mark phase stats.
+	 *
 	 * 3. Runs Mark phase.
+	 *
 	 * 4. Runs Sweep phase.
+	 *
 	 * 5. Generates sweep phase stats.
 	 */
 	private async runGC(
@@ -572,26 +588,24 @@ export class GarbageCollector implements IGarbageCollector {
 		const markPhaseStats = this.getMarkPhaseStats(gcResult);
 
 		// 3. Run the Mark phase.
-		// It will mark nodes as referenced / unreferenced and return a list of node ids that are ready to be swept.
-		const sweepReadyNodeIds = this.runMarkPhase(
+		// It will mark nodes as referenced / unreferenced and return lists of tombstone-ready and sweep-ready nodes.
+		const { tombstoneReadyNodeIds, sweepReadyNodeIds } = this.runMarkPhase(
 			gcResult,
 			allReferencedNodeIds,
 			currentReferenceTimestampMs,
 		);
 
 		// 4. Run the Sweep phase.
-		// It will delete sweep ready nodes and return a list of deleted node ids.
-		const deletedNodeIds = this.runSweepPhase(gcResult, sweepReadyNodeIds);
+		// It will tombstone any tombstone-ready nodes, and initiate the deletion of sweep-ready nodes by sending a
+		// sweep op. All clients, including this one, will delete these nodes once it processes the op.
+		this.runSweepPhase(gcResult, tombstoneReadyNodeIds, sweepReadyNodeIds);
 
-		this.gcDataFromLastRun = cloneGCData(
-			gcData,
-			(id: string) => deletedNodeIds.includes(id) /* filter out deleted nodes */,
-		);
+		this.gcDataFromLastRun = cloneGCData(gcData);
 
 		// 5. Get the sweep phase stats.
 		const sweepPhaseStats = this.getSweepPhaseStats(
-			this.configs.shouldRunSweep ? this.deletedNodes : sweepReadyNodeIds,
-			new Set(deletedNodeIds),
+			this.deletedNodes,
+			sweepReadyNodeIds,
 			markPhaseStats,
 		);
 
@@ -610,13 +624,13 @@ export class GarbageCollector implements IGarbageCollector {
 	 * @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 The sets of tombstone-ready and sweep-ready nodes, i.e., nodes that ready to be tombstoned or deleted.
 	 */
 	private runMarkPhase(
 		gcResult: IGCResult,
 		allReferencedNodeIds: string[],
 		currentReferenceTimestampMs: number,
-	): Set<string> {
+	): { tombstoneReadyNodeIds: Set<string>; sweepReadyNodeIds: Set<string> } {
 		// 1. Marks all referenced nodes by clearing their unreferenced tracker, if any.
 		for (const nodeId of allReferencedNodeIds) {
 			const nodeStateTracker = this.unreferencedNodesState.get(nodeId);
@@ -629,6 +643,7 @@ export class GarbageCollector implements IGarbageCollector {
 		}
 
 		// 2. Mark unreferenced nodes in this run by starting unreferenced tracking for them.
+		const tombstoneReadyNodeIds: Set<string> = new Set();
 		const sweepReadyNodeIds: Set<string> = new Set();
 		for (const nodeId of gcResult.deletedNodeIds) {
 			const nodeStateTracker = this.unreferencedNodesState.get(nodeId);
@@ -640,6 +655,7 @@ export class GarbageCollector implements IGarbageCollector {
 						this.configs.inactiveTimeoutMs,
 						currentReferenceTimestampMs,
 						this.configs.sweepTimeoutMs,
+						this.configs.sweepGracePeriodMs,
 					),
 				);
 			} else {
@@ -647,7 +663,10 @@ export class GarbageCollector implements IGarbageCollector {
 				// is from the ops seen, this will ensure that we keep updating unreferenced state as time moves forward.
 				nodeStateTracker.updateTracking(currentReferenceTimestampMs);
 
-				// If a node is sweep ready, store it so it can be returned.
+				// If a node is tombstone or sweep-ready, store it so it can be returned.
+				if (nodeStateTracker.state === UnreferencedState.TombstoneReady) {
+					tombstoneReadyNodeIds.add(nodeId);
+				}
 				if (nodeStateTracker.state === UnreferencedState.SweepReady) {
 					sweepReadyNodeIds.add(nodeId);
 				}
@@ -657,67 +676,82 @@ export class GarbageCollector implements IGarbageCollector {
 		// 3. Call the runtime to update referenced nodes in this run.
 		this.runtime.updateUsedRoutes(gcResult.referencedNodeIds);
 
-		return sweepReadyNodeIds;
+		return { tombstoneReadyNodeIds, sweepReadyNodeIds };
 	}
 
 	/**
 	 * Runs the GC Sweep phase. It does the following:
-	 * 1. Calls the runtime to delete nodes that are sweep ready.
-	 * 2. Clears tracking for deleted nodes.
+	 *
+	 * 1. Marks tombstone-ready nodes as tombstones.
+	 *
+	 * 2. Sends a sweep op to delete nodes that are sweep-ready. Once the op is ack'd, these nodes will be deleted.
 	 *
 	 * @param gcResult - The result of the GC run on the gcData.
-	 * @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.
+	 * @param tombstoneReadyNodes - List of nodes that are tombstone-ready.
+	 * @param sweepReadyNodes - List of nodes that are sweep-ready.
 	 */
-	private runSweepPhase(gcResult: IGCResult, sweepReadyNodes: Set<string>): string[] {
+	private runSweepPhase(
+		gcResult: IGCResult,
+		tombstoneReadyNodes: Set<string>,
+		sweepReadyNodes: Set<string>,
+	) {
 		/**
-		 * Currently, there are 3 modes for sweep:
-		 * Test mode - Unreferenced nodes are immediately deleted without waiting for them to be sweep ready.
-		 * Tombstone mode - Sweep ready modes are marked as tombstones instead of being deleted.
-		 * Sweep mode - Sweep ready modes are deleted.
+		 * Under "Test Mode", unreferenced nodes are immediately deleted without waiting for them to be sweep-ready.
 		 *
-		 * These modes serve as staging for applications that want to enable sweep by providing an incremental
-		 * way to test and validate sweep works as expected.
+		 * Otherwise, depending on how long it's been since the node was unreferenced, it will either be
+		 * marked as Tombstone, or deleted by Sweep.
 		 */
+
 		if (this.configs.testMode) {
 			// If we are running in GC test mode, unreferenced nodes (gcResult.deletedNodeIds) are deleted.
 			this.runtime.updateUnusedRoutes(gcResult.deletedNodeIds);
-			return [];
+			return;
 		}
 
+		// If sweep is disabled, we'll tombstone both tombstone-ready and sweep-ready nodes.
+		// This is important because a container may never load during a node's Sweep Grace Period,
+		// so that node would directly become sweep-ready skipping over tombstone-ready state,
+		// but should be Tombstoned since Sweep is disabled.
+		const { nodesToTombstone, nodesToDelete } = this.configs.shouldRunSweep
+			? {
+					nodesToTombstone: [...tombstoneReadyNodes],
+					nodesToDelete: [...sweepReadyNodes],
+			  }
+			: {
+					nodesToTombstone: [...tombstoneReadyNodes, ...sweepReadyNodes],
+					nodesToDelete: [],
+			  };
+
 		if (this.configs.tombstoneMode) {
-			this.tombstones = Array.from(sweepReadyNodes);
-			// If we are running in GC tombstone mode, update tombstoned routes. This enables testing scenarios
-			// involving access to "deleted" data without actually deleting the data from summaries.
+			this.tombstones = nodesToTombstone;
+			// If we are running in GC tombstone mode, update tombstoned routes.
 			this.runtime.updateTombstonedRoutes(this.tombstones);
-			return [];
-		}
-
-		if (!this.configs.shouldRunSweep) {
-			return [];
 		}
 
-		// 1. Call the runtime to delete sweep ready nodes. The runtime returns a list of nodes it deleted.
-		// TODO: GC:Validation - validate that removed routes are not double delete and that the child routes of
-		// removed routes are deleted as well.
-		const deletedNodeIds = this.runtime.deleteSweepReadyNodes(Array.from(sweepReadyNodes));
+		if (this.configs.shouldRunSweep && nodesToDelete.length > 0) {
+			// Do not send DDS node ids in the GC op. This is an optimization to reduce its size. Since GC applies to
+			// to data store only, all its DDSes are deleted along with it. The DDS ids will be retrieved from the
+			// local state when processing the op.
+			const sweepReadyDSAndBlobs = nodesToDelete.filter((nodeId) => {
+				const nodeType = this.runtime.getNodeType(nodeId);
+				return nodeType === GCNodeType.DataStore || nodeType === GCNodeType.Blob;
+			});
+			const contents: GarbageCollectionMessage = {
+				type: GarbageCollectionMessageType.Sweep,
+				deletedNodeIds: sweepReadyDSAndBlobs,
+			};
 
-		// 2. Clear unreferenced state tracking for deleted nodes.
-		for (const nodeId of deletedNodeIds) {
-			const nodeStateTracker = this.unreferencedNodesState.get(nodeId);
-			// TODO: GC:Validation - assert that the nodeStateTracker is defined
-			if (nodeStateTracker !== undefined) {
-				// Stop tracking so as to clear out any running timers.
-				nodeStateTracker.stopTracking();
-				// Delete the node as we don't need to track it any more.
-				this.unreferencedNodesState.delete(nodeId);
-			}
-			// TODO: GC:Validation - assert that the deleted node is not a duplicate
-			this.deletedNodes.add(nodeId);
+			// Its fine for older clients to ignore this op because it doesn't have any functional impact. This op
+			// is an optimization to ensure that all clients are in sync when it comes to deleted nodes to prevent their
+			// accidental usage. The clients will sync without the delete op too but it may take longer.
+			const containerGCMessage: ContainerRuntimeGCMessage = {
+				type: ContainerMessageType.GC,
+				contents,
+				compatDetails: { behavior: "Ignore" },
+			};
+			this.submitMessage(containerGCMessage);
+			return;
 		}
-		return deletedNodeIds;
 	}
 
 	/**
@@ -857,6 +891,78 @@ export class GarbageCollector implements IGarbageCollector {
 		return this.summaryStateTracker.refreshLatestSummary(result);
 	}
 
+	/**
+	 * Process a GC message.
+	 * @param message - The GC message from the container runtime.
+	 * @param local - Whether it was send by this client.
+	 */
+	public processMessage(message: ContainerRuntimeGCMessage, local: boolean) {
+		switch (message.contents.type) {
+			case "Sweep": {
+				// Delete the nodes whose ids are present in the contents.
+				this.deleteSweepReadyNodes(message.contents.deletedNodeIds);
+				break;
+			}
+			default: {
+				if (
+					!compatBehaviorAllowsGCMessageType(
+						message.contents.type,
+						message.compatDetails?.behavior,
+					)
+				) {
+					const error = DataProcessingError.create(
+						`Garbage collection message of unknown type ${message.contents.type}`,
+						"processMessage",
+					);
+					throw error;
+				}
+				break;
+			}
+		}
+	}
+
+	/**
+	 * Delete nodes that are sweep-ready. Call the runtime to delete these nodes and clear the unreferenced state
+	 * tracking for nodes that are actually deleted by the runtime.
+	 * @param sweepReadyNodeIds - The ids of nodes that are ready to be deleted.
+	 */
+	private deleteSweepReadyNodes(sweepReadyNodeIds: readonly string[]) {
+		// Use a set for lookup because its much faster than array or map.
+		const sweepReadyNodesSet: Set<string> = new Set(sweepReadyNodeIds);
+
+		// The ids in the sweep-ready nodes do not contain DDS node ids. This is an optimization to reduce the size
+		// of the GC op. Since GC applies to data store only, all its DDSes are deleted along with it. So, get the
+		// DDS nodes ID from the unreferenced nodes state.
+		const allSweepReadyNodeIds = Array.from(sweepReadyNodeIds);
+		for (const [id] of this.unreferencedNodesState) {
+			// Ignore data store nodes since they would already be in the list.
+			const pathParts = id.split("/");
+			if (pathParts.length <= 2) {
+				continue;
+			}
+
+			// Get the data store id part. Note that this may include blobs but that's okay since the part would just
+			// be "_blobs" and it won't be found.
+			const dsId = `/${pathParts[1]}`;
+			if (sweepReadyNodesSet.has(dsId)) {
+				allSweepReadyNodeIds.push(id);
+			}
+		}
+		const deletedNodeIds = this.runtime.deleteSweepReadyNodes(allSweepReadyNodeIds);
+
+		// Clear unreferenced state tracking for deleted nodes.
+		for (const nodeId of deletedNodeIds) {
+			const nodeStateTracker = this.unreferencedNodesState.get(nodeId);
+			if (nodeStateTracker !== undefined) {
+				// Stop tracking so as to clear out any running timers.
+				nodeStateTracker.stopTracking();
+				// Delete the node as we don't need to track it any more.
+				this.unreferencedNodesState.delete(nodeId);
+			}
+			this.deletedNodes.add(nodeId);
+		}
+	}
+
 	/**
 	 * Called when a node with the given id is updated. If the node is inactive or tombstoned, this will log an error
 	 * or throw an error if failing on incorrect usage is configured.
@@ -1036,14 +1142,14 @@ export class GarbageCollector implements IGarbageCollector {
 
 	/**
 	 * Generates the stats of a garbage collection sweep phase run.
-	 * @param allDeletedNodes - All the nodes that have been deleted across all GC runs.
-	 * @param currentDeletedNodes - The nodes that have been deleted in this GC run.
+	 * @param deletedNodes - The nodes that have been deleted until this run.
+	 * @param sweepReadyNodes - The nodes that are sweep-ready in this GC run.
 	 * @param markPhaseStats - The stats of the mark phase run.
 	 * @returns the stats of the sweep phase run.
 	 */
 	private getSweepPhaseStats(
-		allDeletedNodes: Set<string>,
-		currentDeletedNodes: Set<string>,
+		deletedNodes: Set<string>,
+		sweepReadyNodes: Set<string>,
 		markPhaseStats: IMarkPhaseStats,
 	): ISweepPhaseStats {
 		// Initialize the life time node counts to the mark phase node counts. If sweep is not enabled,
@@ -1057,7 +1163,7 @@ export class GarbageCollector implements IGarbageCollector {
 			deletedAttachmentBlobCount: 0,
 		};
 
-		for (const nodeId of allDeletedNodes) {
+		for (const nodeId of deletedNodes) {
 			sweepPhaseStats.deletedNodeCount++;
 			const nodeType = this.runtime.getNodeType(nodeId);
 			if (nodeType === GCNodeType.DataStore) {
@@ -1067,25 +1173,26 @@ export class GarbageCollector implements IGarbageCollector {
 			}
 		}
 
-		if (!this.configs.shouldRunSweep) {
-			return sweepPhaseStats;
-		}
-
 		// If sweep is enabled, the counts from the mark phase stats do not include nodes that have been
-		// deleted in previous runs. Add the deleted node counts to life time stats.
+		// deleted in previous runs. So, add the deleted node counts to life time stats.
 		sweepPhaseStats.lifetimeNodeCount += sweepPhaseStats.deletedNodeCount;
 		sweepPhaseStats.lifetimeDataStoreCount += sweepPhaseStats.deletedDataStoreCount;
 		sweepPhaseStats.lifetimeAttachmentBlobCount += sweepPhaseStats.deletedAttachmentBlobCount;
 
-		// The node deleted in current run are counted twice - once in allDeletedNodes and again in
-		// markPhaseStats. So, remove them from the life time stats.
-		for (const nodeId of currentDeletedNodes) {
-			sweepPhaseStats.lifetimeNodeCount--;
+		if (this.configs.shouldRunSweep) {
+			return sweepPhaseStats;
+		}
+
+		// If sweep is not enabled, the current sweep-ready node stats should be added to deleted stats since this
+		// is the final state the node will be in.
+		// If sweep is enabled, this will happen in the run after the GC op round trips back.
+		for (const nodeId of sweepReadyNodes) {
+			sweepPhaseStats.deletedNodeCount++;
 			const nodeType = this.runtime.getNodeType(nodeId);
 			if (nodeType === GCNodeType.DataStore) {
-				sweepPhaseStats.lifetimeDataStoreCount--;
+				sweepPhaseStats.deletedDataStoreCount++;
 			} else if (nodeType === GCNodeType.Blob) {
-				sweepPhaseStats.lifetimeAttachmentBlobCount--;
+				sweepPhaseStats.deletedAttachmentBlobCount++;
 			}
 		}
 		return sweepPhaseStats;

package/src/gc/gcConfigs.ts

@@ -3,7 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { MonitoringContext, UsageError } from "@fluidframework/telemetry-utils";
+import {
+	MonitoringContext,
+	UsageError,
+	validatePrecondition,
+} from "@fluidframework/telemetry-utils";
 import { IContainerRuntimeMetadata } from "../summary";
 import {
 	nextGCVersion,
@@ -11,9 +15,7 @@ import {
 	defaultSessionExpiryDurationMs,
 	disableTombstoneKey,
 	GCFeatureMatrix,
-	gcSweepGenerationOptionName,
 	gcTestModeKey,
-	gcTombstoneGenerationOptionName,
 	GCVersion,
 	gcVersionUpgradeToV4Key,
 	IGarbageCollectorConfigs,
@@ -26,9 +28,11 @@ import {
 	stableGCVersion,
 	throwOnTombstoneLoadOverrideKey,
 	throwOnTombstoneUsageKey,
-	gcThrowOnTombstoneLoadOptionName,
+	gcDisableThrowOnTombstoneLoadOptionName,
+	defaultSweepGracePeriodMs,
+	gcGenerationOptionName,
 } from "./gcDefinitions";
-import { getGCVersion, shouldAllowGcSweep, shouldAllowGcTombstoneEnforcement } from "./gcHelpers";
+import { getGCVersion, shouldAllowGcSweep } from "./gcHelpers";
 
 /**
  * Generates configurations for the Garbage Collector that it uses to determine what to run and how.
@@ -71,14 +75,6 @@ export function generateGCConfigs(
 			createParams.metadata?.sweepTimeoutMs ?? computeSweepTimeout(sessionExpiryTimeoutMs); // Backfill old documents that didn't persist this
 		persistedGcFeatureMatrix = createParams.metadata?.gcFeatureMatrix;
 	} else {
-		const tombstoneGeneration = createParams.gcOptions[gcTombstoneGenerationOptionName];
-		const sweepGeneration = createParams.gcOptions[gcSweepGenerationOptionName];
-
-		// Sweep should not be enabled (via sweepGeneration value) without enabling GC mark phase.
-		if (sweepGeneration !== undefined && createParams.gcOptions.gcAllowed === false) {
-			throw new UsageError("GC sweep phase cannot be enabled without enabling GC mark phase");
-		}
-
 		// This Test Override only applies for new containers
 		const testOverrideSweepTimeoutMs = mc.config.getNumber(
 			"Fluid.GarbageCollection.TestOverride.SweepTimeoutMs",
@@ -95,18 +91,18 @@ export function generateGCConfigs(
 		}
 		sweepTimeoutMs = testOverrideSweepTimeoutMs ?? computeSweepTimeout(sessionExpiryTimeoutMs);
 
-		if (tombstoneGeneration !== undefined || sweepGeneration !== undefined) {
-			persistedGcFeatureMatrix = {
-				tombstoneGeneration,
-				sweepGeneration,
-			};
+		const gcGeneration = createParams.gcOptions[gcGenerationOptionName];
+		if (gcGeneration !== undefined) {
+			persistedGcFeatureMatrix = { gcGeneration };
 		}
 	}
 
-	// Is sweepEnabled for this document?
-	const sweepEnabled = shouldAllowGcSweep(
-		persistedGcFeatureMatrix ?? {} /* persistedGenerations */,
-		createParams.gcOptions[gcSweepGenerationOptionName] /* currentGeneration */,
+	// The persisted GC generation must indicate Sweep is allowed for this document,
+	// according to the GC Generation option provided this session.
+	// Note that if no generation option is provided, Sweep is allowed for any document.
+	const sweepAllowed = shouldAllowGcSweep(
+		persistedGcFeatureMatrix ?? {} /* featureMatrix */,
+		createParams.gcOptions[gcGenerationOptionName] /* currentGeneration */,
 	);
 
 	// If version upgrade is not enabled, fall back to the stable GC version.
@@ -123,27 +119,30 @@ export function generateGCConfigs(
 	 * Whether GC should run or not. The following conditions have to be met to run sweep:
 	 * 1. GC should be enabled for this container.
 	 * 2. GC should not be disabled via disableGC GC option.
-	 * 3. The current GC version should be greater of equal to the GC version in the base snapshot.
-	 * These conditions can be overridden via runGCKey feature flag.
+	 * 3. The current GC version should be greater or equal to the GC version in the base snapshot.
+	 *
+	 * These conditions can be overridden via the RunGC feature flag.
 	 */
 	const shouldRunGC =
 		mc.config.getBoolean(runGCKey) ??
 		(gcEnabled && !createParams.gcOptions.disableGC && isGCVersionUpToDate);
 
 	/**
-	 * Whether sweep should run or not. The following conditions have to be met to run sweep:
+	 * Whether sweep should run or not. This refers to whether Tombstones should fail on load and whether
+	 * sweep-ready nodes should be deleted.
 	 *
-	 * 1. Overall GC or mark phase must be enabled (this.configs.shouldRunGC).
-	 * 2. Sweep timeout should be available. Without this, we wouldn't know when an object should be deleted.
-	 * 3. The driver must implement the policy limiting the age of snapshots used for loading. Otherwise
-	 * the Sweep Timeout calculation is not valid. We use the persisted value to ensure consistency over time.
-	 * 4. Sweep should be enabled for this container. This can be overridden via runSweep
-	 * feature flag.
+	 * Assuming overall GC is enabled and sweepTimeout is provided, the following conditions have to be met to run sweep:
+	 *
+	 * 1. Sweep should be enabled for this container.
+	 * 2. Sweep should be enabled for this session.
+	 *
+	 * These conditions can be overridden via the RunSweep feature flag.
 	 */
 	const shouldRunSweep =
-		shouldRunGC &&
-		sweepTimeoutMs !== undefined &&
-		(mc.config.getBoolean(runSweepKey) ?? sweepEnabled);
+		!shouldRunGC || sweepTimeoutMs === undefined
+			? false
+			: mc.config.getBoolean(runSweepKey) ??
+			  (sweepAllowed && createParams.gcOptions.enableGCSweep === true);
 
 	// Override inactive timeout if test config or gc options to override it is set.
 	const inactiveTimeoutMs =
@@ -159,46 +158,45 @@ export function generateGCConfigs(
 	// 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;
-	// Whether we are running in tombstone mode. This is enabled by default if sweep won't run. It can be disabled
-	// via feature flags.
-	const tombstoneMode = !shouldRunSweep && mc.config.getBoolean(disableTombstoneKey) !== true;
+	// Whether we are running in tombstone mode. If disabled, tombstone data will not be written to or read from snapshots,
+	// and objects will not be marked as tombstoned even if they pass to the "TombstoneReady" state during the session.
+	const tombstoneMode = mc.config.getBoolean(disableTombstoneKey) !== true;
 	const runFullGC = createParams.gcOptions.runFullGC;
 
+	const sweepGracePeriodMs =
+		createParams.gcOptions.sweepGracePeriodMs ?? defaultSweepGracePeriodMs;
+	validatePrecondition(sweepGracePeriodMs >= 0, "sweepGracePeriodMs must be non-negative", {
+		sweepGracePeriodMs,
+	});
+
 	const throwOnInactiveLoad: boolean | undefined = createParams.gcOptions.throwOnInactiveLoad;
-	const tombstoneEnforcementAllowed = shouldAllowGcTombstoneEnforcement(
-		createParams.metadata?.gcFeatureMatrix?.tombstoneGeneration /* persisted */,
-		createParams.gcOptions[gcTombstoneGenerationOptionName] /* current */,
-	);
 
 	const throwOnTombstoneLoadConfig =
 		mc.config.getBoolean(throwOnTombstoneLoadOverrideKey) ??
-		createParams.gcOptions[gcThrowOnTombstoneLoadOptionName] ??
-		false;
+		createParams.gcOptions[gcDisableThrowOnTombstoneLoadOptionName] !== true;
 	const throwOnTombstoneLoad =
-		throwOnTombstoneLoadConfig &&
-		tombstoneEnforcementAllowed &&
-		!createParams.isSummarizerClient;
+		throwOnTombstoneLoadConfig && sweepAllowed && !createParams.isSummarizerClient;
 	const throwOnTombstoneUsage =
 		mc.config.getBoolean(throwOnTombstoneUsageKey) === true &&
-		tombstoneEnforcementAllowed &&
+		sweepAllowed &&
 		!createParams.isSummarizerClient;
 
 	return {
-		gcEnabled,
-		sweepEnabled,
-		shouldRunGC,
-		shouldRunSweep,
+		gcEnabled, // For this document
+		sweepEnabled: sweepAllowed, // For this document (based on current GC Generation option)
+		shouldRunGC, // For this session
+		shouldRunSweep, // For this session
 		runFullGC,
 		testMode,
 		tombstoneMode,
 		sessionExpiryTimeoutMs,
 		sweepTimeoutMs,
+		sweepGracePeriodMs,
 		inactiveTimeoutMs,
 		persistedGcFeatureMatrix,
 		gcVersionInBaseSnapshot,
 		gcVersionInEffect,
 		throwOnInactiveLoad,
-		tombstoneEnforcementAllowed,
 		throwOnTombstoneLoad,
 		throwOnTombstoneUsage,
 	};