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

package/src/gc/gcDefinitions.ts

@@ -20,6 +20,7 @@ import {
 	IRefreshSummaryResult,
 } from "../summary";
 import { RuntimeHeaderData } from "../containerRuntime";
+import { ContainerRuntimeGCMessage } from "../messageTypes";
 
 /**
  * @alpha
@@ -32,27 +33,25 @@ export const stableGCVersion: GCVersion = 3;
 export const nextGCVersion: GCVersion = 4;
 
 /**
- * This undocumented GC Option (on ContainerRuntime Options) allows an app to disable enforcing GC on old documents by incrementing this value
+ * This undocumented GC Option (on ContainerRuntime Options) allows an app to disable throwing an error when tombstone
+ * object is loaded (requested), merely logging a message instead.
  *
- * If unset, GC Tombstone phase will operate as otherwise configured
- * Otherwise, only enforce GC Tombstone if the passed in value matches the persisted value
+ * By default, attempting to load a Tombstoned object will result in an error.
  */
-export const gcTombstoneGenerationOptionName = "gcTombstoneGeneration";
+export const gcDisableThrowOnTombstoneLoadOptionName = "gcDisableThrowOnTombstoneLoad";
 
 /**
- * This undocumented GC Option (on ContainerRuntime Options) allows an app to enable throwing an error when tombstone
- * object is loaded (requested).
- */
-export const gcThrowOnTombstoneLoadOptionName = "gcThrowOnTombstoneLoad";
-
-/**
- * This GC Option (on ContainerRuntime Options) allows an app to disable GC Sweep on old documents by incrementing this value.
+ * This undocumented GC Option (on ContainerRuntime Options) allows configuring which documents can have Sweep enabled.
+ * This provides a way to disable both Tombstone Enforcement and Sweep.
  *
- * If unset altogether, Sweep will be disabled.
- * If 0 is passed in, Sweep will be enabled for any document with gcSweepGeneration OR gcTombstoneGeneration as 0.
- * If any other number is passed in, Sweep will be enabled only for documents with the same value persisted.
+ * If unset, Tombstone Enforcement + Sweep will operate as otherwise configured.
+ * Otherwise, the Sweep Phase will be disabled for documents where persisted value doesn't match what is passed into this session.
+ * This provides a way to disallow Sweep for old documents that may be too difficult for an app to repair,
+ * in case a bug is found that violates GC's assumptions.
+ *
+ * @see GCFeatureMatrix (gcGeneration)
  */
-export const gcSweepGenerationOptionName = "gcSweepGeneration";
+export const gcGenerationOptionName = "gcGeneration";
 
 /** Config key to turn GC on / off. */
 export const runGCKey = "Fluid.GarbageCollection.RunGC";
@@ -89,25 +88,30 @@ export const maxSnapshotCacheExpiryMs = 5 * oneDayMs;
 
 export const defaultInactiveTimeoutMs = 7 * oneDayMs; // 7 days
 export const defaultSessionExpiryDurationMs = 30 * oneDayMs; // 30 days
+export const defaultSweepGracePeriodMs = 1 * oneDayMs; // 1 day
 
 /**
- * @see IGCMetadata.gcFeatureMatrix
+ * @see IGCMetadata.gcFeatureMatrix and @see gcGenerationOptionName
  * @alpha
  */
-export interface GCFeatureMatrix {
-	/**
-	 * The Tombstone Generation value in effect when this file was created.
-	 * Gives a way for an app to disqualify old files from GC Tombstone enforcement.
-	 * Provided via Container Runtime Options.
-	 */
-	tombstoneGeneration?: number;
-	/**
-	 * The Sweep Generation value in effect when this file was created.
-	 * Gives a way for an app to disqualify old files from GC Sweep.
-	 * Provided via Container Runtime Options.
-	 */
-	sweepGeneration?: number;
-}
+export type GCFeatureMatrix =
+	| {
+			/**
+			 * The GC Generation value in effect when this file was created.
+			 * Gives a way for an app to disqualify old files from GC Sweep.
+			 * Provided via Container Runtime Options.
+			 */
+			gcGeneration?: number;
+			/** Deprecated property from legacy type. Will not be set concurrently with gcGeneration */
+			tombstoneGeneration?: undefined;
+	  }
+	| {
+			/**
+			 * The Tombstone Generation value in effect when this file was created.
+			 * Legacy - new containers would get gcGeneration instead (if anything)
+			 */
+			tombstoneGeneration: number;
+	  };
 
 /**
  * @alpha
@@ -139,7 +143,7 @@ export interface IGCMetadata {
 	 * - True means sweep phase is enabled.
 	 * - False means sweep phase is disabled. If GC is disabled as per gcFeature, sweep is also disabled.
 	 *
-	 * @deprecated use GCFeatureMatrix.sweepGeneration instead. @see GCFeatureMatrix.sweepGeneration
+	 * @deprecated use GCFeatureMatrix.gcGeneration instead. @see GCFeatureMatrix.gcGeneration
 	 */
 	readonly sweepEnabled?: boolean;
 	/** If this is present, the session for this container will expire after this time and the container will close */
@@ -218,6 +222,37 @@ export const GCNodeType = {
  */
 export type GCNodeType = (typeof GCNodeType)[keyof typeof GCNodeType];
 
+/**
+ * The type of a garbage collection message.
+ * @internal
+ */
+export const GarbageCollectionMessageType = {
+	/** Message sent directing GC to delete the given nodes */
+	Sweep: "Sweep",
+} as const;
+
+/**
+ * @internal
+ */
+export type GarbageCollectionMessageType =
+	(typeof GarbageCollectionMessageType)[keyof typeof GarbageCollectionMessageType];
+
+/**
+ * The garbage collection sweep message.
+ * @internal
+ */
+export interface ISweepMessage {
+	type: "Sweep";
+	// The ids of nodes that are deleted.
+	deletedNodeIds: string[];
+}
+
+/**
+ * Type for a message to be used for sending / received garbage collection messages.
+ * @internal
+ */
+export type GarbageCollectionMessage = ISweepMessage;
+
 /**
  * Defines the APIs for the runtime object to be passed to the garbage collector.
  */
@@ -227,17 +262,17 @@ export interface IGarbageCollectionRuntime {
 	/** Returns the garbage collection data of the runtime. */
 	getGCData(fullGC?: boolean): Promise<IGarbageCollectionData>;
 	/** After GC has run, called to notify the runtime of routes that are used in it. */
-	updateUsedRoutes(usedRoutes: string[]): void;
+	updateUsedRoutes(usedRoutes: readonly string[]): void;
 	/** After GC has run, called to notify the runtime of routes that are unused in it. */
-	updateUnusedRoutes(unusedRoutes: string[]): void;
+	updateUnusedRoutes(unusedRoutes: readonly string[]): void;
 	/**
 	 * After GC has run and identified nodes that are sweep ready, called to delete the sweep ready nodes. The runtime
 	 * should return the routes of nodes that were deleted.
 	 * @param sweepReadyRoutes - The routes of nodes that are sweep ready and should be deleted.
 	 */
-	deleteSweepReadyNodes(sweepReadyRoutes: string[]): string[];
+	deleteSweepReadyNodes(sweepReadyRoutes: readonly string[]): readonly string[];
 	/** Called to notify the runtime of routes that are tombstones. */
-	updateTombstonedRoutes(tombstoneRoutes: string[]): void;
+	updateTombstonedRoutes(tombstoneRoutes: readonly string[]): void;
 	/** Returns a referenced timestamp to be used to track unreferenced nodes. */
 	getCurrentReferenceTimestampMs(): number | undefined;
 	/** Returns the type of the GC node. */
@@ -297,6 +332,8 @@ export interface IGarbageCollector {
 	): void;
 	/** Called when a reference is added to a node. Used to identify nodes that were referenced between summaries. */
 	addedOutboundReference(fromNodePath: string, toNodePath: string): void;
+	/** Called to process a garbage collection message. */
+	processMessage(message: ContainerRuntimeGCMessage, local: boolean): void;
 	/** Returns true if this node has been deleted by GC during sweep phase. */
 	isNodeDeleted(nodePath: string): boolean;
 	setConnectionState(connected: boolean, clientId?: string): void;
@@ -317,6 +354,7 @@ export interface IGarbageCollectorCreateParams {
 	readonly getLastSummaryTimestampMs: () => number | undefined;
 	readonly readAndParseBlob: ReadAndParseBlob;
 	readonly activeConnection: () => boolean;
+	readonly submitMessage: (message: ContainerRuntimeGCMessage) => void;
 }
 
 /**
@@ -329,7 +367,7 @@ export interface IGCRuntimeOptions {
 	 * GC has mark phase and sweep phase. In mark phase, unreferenced objects are identified
 	 * and marked as such in the summary. This option enables the mark phase.
 	 * In sweep phase, unreferenced objects are eventually deleted from the container if they meet certain conditions.
-	 * Sweep phase can be enabled using the "gcSweepGeneration" option.
+	 * Sweep phase can be enabled using the "enableGCSweep" option.
 	 *
 	 * Note: This setting is persisted in the container's summary and cannot be changed.
 	 */
@@ -341,6 +379,17 @@ export interface IGCRuntimeOptions {
 	 */
 	disableGC?: boolean;
 
+	/**
+	 * Flag that if true, will enable the full Sweep Phase of garbage collection for this session,
+	 * where Tombstoned objects are permanently deleted from the container.
+	 *
+	 * IMPORTANT: This only applies if this document is allowed to run Sweep Phase.
+	 *
+	 * Current default behavior is for Sweep Phase not to delete Tombstoned objects,
+	 * but merely to prevent them from being loaded.
+	 */
+	enableGCSweep?: true;
+
 	/**
 	 * Flag that will bypass optimizations and generate GC data for all nodes irrespective of whether a node
 	 * changed or not.
@@ -354,6 +403,13 @@ export interface IGCRuntimeOptions {
 	 */
 	sessionExpiryTimeoutMs?: number;
 
+	/**
+	 * Delay between when Tombstone should run and when the object should be deleted.
+	 * This grace period gives a chance to intervene to recover if needed, before Sweep deletes the object.
+	 * If not present, a default (non-zero) value will be used.
+	 */
+	sweepGracePeriodMs?: number;
+
 	/**
 	 * Allows additional GC options to be passed.
 	 */
@@ -392,15 +448,21 @@ export interface IGarbageCollectorConfigs {
 	readonly sessionExpiryTimeoutMs: number | undefined;
 	/** The time after which an unreferenced node is ready to be swept. */
 	readonly sweepTimeoutMs: number | undefined;
+	/**
+	 * The delay between tombstone and sweep. Not persisted, so concurrent sessions may use different values.
+	 * Sweep is implemented in an eventually-consistent way so this is acceptable.
+	 */
+	readonly sweepGracePeriodMs: number;
 	/** The time after which an unreferenced node is inactive. */
 	readonly inactiveTimeoutMs: number;
 	/** Tracks whether GC should run in test mode. In this mode, unreferenced objects are deleted immediately. */
 	readonly testMode: boolean;
 	/**
-	 * Tracks whether GC should run in tombstone mode. In this mode, sweep ready objects are marked as tombstones.
+	 * Tracks whether GC should run in tombstone mode. In this mode, objects are marked as tombstones as a step along the
+	 * way before they are fully deleted.
 	 * In interactive (non-summarizer) clients, tombstone objects behave as if they are deleted, i.e., access to them
-	 * is not allowed. However, these objects can be accessed after referencing them first. It is used as a staging
-	 * step for sweep where accidental sweep ready objects can be recovered.
+	 * is not allowed. However, these objects can be accessed after referencing them first. It is used as a "warning"
+	 * step before sweep, where objects wrongly marked as unreferenced can be recovered.
 	 */
 	readonly tombstoneMode: boolean;
 	/** @see GCFeatureMatrix. */
@@ -411,8 +473,6 @@ export interface IGarbageCollectorConfigs {
 	readonly gcVersionInEffect: GCVersion;
 	/** It is easier for users to diagnose InactiveObject usage if we throw on load, which this option enables */
 	readonly throwOnInactiveLoad: boolean | undefined;
-	/** If false, loading or using a Tombstoned object should merely log, not fail */
-	readonly tombstoneEnforcementAllowed: boolean;
 	/** If true, throw an error when a tombstone data store is retrieved */
 	readonly throwOnTombstoneLoad: boolean;
 	/** If true, throw an error when a tombstone data store is used. */
@@ -425,6 +485,8 @@ export const UnreferencedState = {
 	Active: "Active",
 	/** The node is inactive, i.e., it should not become referenced. */
 	Inactive: "Inactive",
+	/** The node is ready to be tombstoned */
+	TombstoneReady: "TombstoneReady",
 	/** The node is ready to be deleted by the sweep phase. */
 	SweepReady: "SweepReady",
 } as const;

package/src/gc/gcHelpers.ts

@@ -28,64 +28,34 @@ export function getGCVersion(metadata?: IGCMetadata): GCVersion {
 }
 
 /**
- * Indicates whether Tombstone Enforcement is allowed for this document based on the current/persisted
- * TombstoneGeneration values
- *
- * In order to protect old documents that were created at a time when known bugs exist that violate GC's invariants
- * such that enforcing GC Tombstone (Failing on Tombstone load/usage) would cause legitimate data loss,
- * the container author may increment the generation value for Tombstone such that containers created
- * with a different value will not be subjected to GC enforcement.
- *
- * If no generation is provided at runtime, this defaults to return true to maintain expected default behavior
- *
- * @param persistedGeneration - The persisted tombstoneGeneration value
- * @param currentGeneration - The current app-provided tombstoneGeneration value
- * @returns true if GC Tombstone enforcement (Fail on Tombstone load/usage) should be allowed for this document
- */
-export function shouldAllowGcTombstoneEnforcement(
-	persistedGeneration: number | undefined,
-	currentGeneration: number | undefined,
-): boolean {
-	// If no Generation value is provided for this session, then we should default to letting Tombstone feature behave as intended.
-	if (currentGeneration === undefined) {
-		return true;
-	}
-	return persistedGeneration === currentGeneration;
-}
-
-/**
- * Indicates whether Sweep is allowed for this document based on the GC Feature Matrix and current SweepGeneration
+ * Indicates whether Sweep is allowed for this document based on the persisted GC Feature Matrix and current gcGeneration.
+ * This applies to the entire Sweep Phase the same - both Tombstone Enforcement (i.e. should loading a Tombstone fail?) and Deletion.
  *
  * In order to protect old documents that were created at a time when known bugs exist that violate GC's invariants
  * such that enforcing GC Sweep would cause legitimate data loss, the container author may increment the generation value for Sweep
  * such that containers created with a different value will not be subjected to GC Sweep.
  *
- * If no generation is provided, Sweep will be disabled.
- * Passing 0 is a special case: Sweep will be enabled for any document with gcSweepGeneration OR gcTombstoneGeneration as 0.
+ * If no generation is provided, Sweep will be enabled for all documents.
+ *
+ * For backwards compatibility, the current generation value is also compared against the persisted gcTombstoneGeneration if present.
  *
- * @param persistedGenerations - The persisted sweep/tombstone generations from the GC Feature Matrix
- * @param currentGeneration - The current app-provided sweepGeneration value
+ * @param featureMatrix - The GC Feature Matrix, containing the persisted generation value
+ * @param currentGeneration - The current app-provided gcGeneration value
  * @returns true if GC Sweep should be allowed for this document
  */
 export function shouldAllowGcSweep(
-	persistedGenerations: Pick<GCFeatureMatrix, "sweepGeneration" | "tombstoneGeneration">,
+	featureMatrix: GCFeatureMatrix,
 	currentGeneration: number | undefined,
 ): boolean {
-	// If no Generation value is provided for this session, default to false
+	// If no Generation value is provided for this session, default to true
 	if (currentGeneration === undefined) {
-		return false;
+		return true;
 	}
 
-	// 0 is a special case: It matches both SweepGeneration and TombstoneGeneration
-	// This is an optimistic measure to maximize coverage of GC Sweep if no bumps to TombstoneGeneration are needed before enabling Sweep.
-	if (currentGeneration === 0) {
-		return (
-			persistedGenerations.sweepGeneration === 0 ||
-			persistedGenerations.tombstoneGeneration === 0
-		);
-	}
+	// tombstoneGeneration is the predecessor and needs to be supported for back-compat reasons
+	const targetGeneration = featureMatrix.tombstoneGeneration ?? featureMatrix.gcGeneration;
 
-	return persistedGenerations.sweepGeneration === currentGeneration;
+	return currentGeneration === targetGeneration;
 }
 
 /**
@@ -151,19 +121,12 @@ export function concatGarbageCollectionStates(
 /**
  * Helper function that clones the GC data.
  * @param gcData - The GC data to clone.
- * @param filter - Optional function to filter out node ids not to be included in the cloned GC data. Returns
- * true to filter out nodes.
  * @returns a clone of the given GC data.
  */
-export function cloneGCData(
-	gcData: IGarbageCollectionData,
-	filter?: (id: string) => boolean,
-): IGarbageCollectionData {
+export function cloneGCData(gcData: IGarbageCollectionData): IGarbageCollectionData {
 	const clonedGCNodes: { [id: string]: string[] } = {};
 	for (const [id, outboundRoutes] of Object.entries(gcData.gcNodes)) {
-		if (filter?.(id) !== true) {
-			clonedGCNodes[id] = Array.from(outboundRoutes);
-		}
+		clonedGCNodes[id] = Array.from(outboundRoutes);
 	}
 	return {
 		gcNodes: clonedGCNodes,
@@ -303,3 +266,19 @@ export function unpackChildNodesGCDetails(gcDetails: IGarbageCollectionDetailsBa
 export function trimLeadingAndTrailingSlashes(str: string) {
 	return str.replace(/^\/+|\/+$/g, "");
 }
+
+/**
+ * Utility to implement compat behaviors given an unknown message type
+ * The parameters are typed to support compile-time enforcement of handling all known types/behaviors
+ *
+ * @param _unknownGCMessageType - Typed as never to ensure all known types have been
+ * handled before calling this function (e.g. in a switch statement).
+ * @param compatBehavior - Typed redundantly with CompatModeBehavior to ensure handling is added when updating that type
+ */
+export function compatBehaviorAllowsGCMessageType(
+	_unknownGCMessageType: never,
+	compatBehavior: "Ignore" | "FailToProcess" | undefined,
+): boolean {
+	// undefined defaults to same behavior as "FailToProcess"
+	return compatBehavior === "Ignore";
+}

package/src/gc/gcTelemetry.ts

@@ -142,6 +142,21 @@ export class GCTelemetryTracker {
 
 		const nodeStateTracker = this.getNodeStateTracker(nodeUsageProps.id);
 		const nodeType = this.getNodeType(nodeUsageProps.id);
+		const timeout = (() => {
+			switch (nodeStateTracker?.state) {
+				case UnreferencedState.Inactive:
+					return this.configs.inactiveTimeoutMs;
+				case UnreferencedState.TombstoneReady:
+					return this.configs.sweepTimeoutMs;
+				case UnreferencedState.SweepReady:
+					return (
+						this.configs.sweepTimeoutMs &&
+						this.configs.sweepTimeoutMs + this.configs.sweepGracePeriodMs
+					);
+				default:
+					return undefined;
+			}
+		})();
 		const {
 			usageType,
 			currentReferenceTimestampMs,
@@ -159,10 +174,7 @@ export class GCTelemetryTracker {
 					? nodeUsageProps.currentReferenceTimestampMs -
 					  nodeStateTracker.unreferencedTimestampMs
 					: -1,
-			timeout:
-				nodeStateTracker?.state === UnreferencedState.Inactive
-					? this.configs.inactiveTimeoutMs
-					: this.configs.sweepTimeoutMs,
+			timeout,
 			...tagCodeArtifacts({ id: untaggedId, fromId: untaggedFromId }),
 			...propsToLog,
 			...this.createContainerMetadata,

package/src/gc/gcUnreferencedStateTracker.ts

@@ -4,6 +4,7 @@
  */
 
 import { assert, Timer } from "@fluidframework/core-utils";
+import { validatePrecondition } from "@fluidframework/telemetry-utils";
 import { UnreferencedState } from "./gcDefinitions";
 
 /** A wrapper around common-utils Timer that requires the timeout when calling start/restart */
@@ -26,7 +27,7 @@ class TimerWithNoDefaultTimeout extends Timer {
 
 /**
  * Helper class that tracks the state of an unreferenced node such as the time it was unreferenced and if it can
- * be deleted by the sweep phase.
+ * be tombstoned or deleted by the sweep phase.
  */
 export class UnreferencedStateTracker {
 	private _state: UnreferencedState = UnreferencedState.Active;
@@ -36,6 +37,8 @@ export class UnreferencedStateTracker {
 
 	/** Timer to indicate when an unreferenced object is considered Inactive */
 	private readonly inactiveTimer: TimerWithNoDefaultTimeout;
+	/** Timer to indicate when an unreferenced object is Tombstone-Ready */
+	private readonly tombstoneTimer: TimerWithNoDefaultTimeout;
 	/** Timer to indicate when an unreferenced object is Sweep-Ready */
 	private readonly sweepTimer: TimerWithNoDefaultTimeout;
 
@@ -45,32 +48,49 @@ export class UnreferencedStateTracker {
 		private readonly inactiveTimeoutMs: number,
 		/** The current reference timestamp used to track how long this node has been unreferenced for. */
 		currentReferenceTimestampMs: number,
-		/** The time after which node transitions to SweepReady state; undefined if session expiry is disabled. */
-		private readonly sweepTimeoutMs: number | undefined,
+		/** The time after which node transitions to TombstoneReady state; undefined if session expiry is disabled. */
+		private readonly tombstoneTimeoutMs: number | undefined,
+		/** The delay from TombstoneReady to SweepReady (only applies if tombstoneTimeoutMs is defined) */
+		private readonly sweepGracePeriodMs: number,
 	) {
-		if (this.sweepTimeoutMs !== undefined) {
-			assert(
-				this.inactiveTimeoutMs <= this.sweepTimeoutMs,
-				0x3b0 /* inactive timeout must not be greater than the sweep timeout */,
-			);
-		}
+		validatePrecondition(
+			this.tombstoneTimeoutMs === undefined ||
+				this.tombstoneTimeoutMs >= this.inactiveTimeoutMs,
+			"inactiveTimeoutMs must not be greater than the tombstoneTimeoutMs",
+		);
 
 		this.sweepTimer = new TimerWithNoDefaultTimeout(() => {
 			this._state = UnreferencedState.SweepReady;
 			assert(
-				!this.inactiveTimer.hasTimer,
-				0x3b1 /* inactiveTimer still running after sweepTimer fired! */,
+				!this.inactiveTimer.hasTimer && !this.tombstoneTimer.hasTimer,
+				0x863 /* inactiveTimer or tombstoneTimer still running after sweepTimer fired! */,
 			);
 		});
 
+		this.tombstoneTimer = new TimerWithNoDefaultTimeout(() => {
+			this._state = UnreferencedState.TombstoneReady;
+			assert(
+				!this.inactiveTimer.hasTimer,
+				0x864 /* inactiveTimer still running after tombstoneTimer fired! */,
+			); // aka 0x3b1
+
+			if (this.sweepGracePeriodMs > 0) {
+				// After the node becomes tombstone ready, start the sweep timer after which the node will be ready for sweep.
+				this.sweepTimer.restart(this.sweepGracePeriodMs);
+			} else {
+				this._state = UnreferencedState.SweepReady;
+			}
+		});
+
 		this.inactiveTimer = new TimerWithNoDefaultTimeout(() => {
 			this._state = UnreferencedState.Inactive;
 
-			// After the node becomes inactive, start the sweep timer after which the node will be ready for sweep.
-			if (this.sweepTimeoutMs !== undefined) {
-				this.sweepTimer.restart(this.sweepTimeoutMs - this.inactiveTimeoutMs);
+			// After the node becomes inactive, start the tombstone timer after which the node will be ready for tombstone.
+			if (this.tombstoneTimeoutMs !== undefined) {
+				this.tombstoneTimer.restart(this.tombstoneTimeoutMs - this.inactiveTimeoutMs);
 			}
 		});
+
 		this.updateTracking(currentReferenceTimestampMs);
 	}
 
@@ -78,21 +98,39 @@ export class UnreferencedStateTracker {
 	public updateTracking(currentReferenceTimestampMs: number) {
 		const unreferencedDurationMs = currentReferenceTimestampMs - this.unreferencedTimestampMs;
 
-		// If the node has been unreferenced for sweep timeout amount of time, update the state to SweepReady.
-		if (this.sweepTimeoutMs !== undefined && unreferencedDurationMs >= this.sweepTimeoutMs) {
+		// Below we will set the appropriate timer (or none). Any running timers are superceded by the new currentReferenceTimestampMs
+		this.clearTimers();
+
+		// If the node has been unreferenced long enough, update the state to SweepReady.
+		if (
+			this.tombstoneTimeoutMs !== undefined &&
+			unreferencedDurationMs >= this.tombstoneTimeoutMs + this.sweepGracePeriodMs
+		) {
 			this._state = UnreferencedState.SweepReady;
-			this.clearTimers();
 			return;
 		}
 
-		// If the node has been unreferenced for inactive timeoutMs amount of time, update the state to inactive.
-		// Also, start a timer for the sweep timeout.
+		// If the node has been unreferenced long enough, update the state to TombstoneReady.
+		// Also, start a timer for the remainder of the sweep delay.
+		if (
+			this.tombstoneTimeoutMs !== undefined &&
+			unreferencedDurationMs >= this.tombstoneTimeoutMs
+		) {
+			this._state = UnreferencedState.TombstoneReady;
+
+			this.sweepTimer.restart(
+				this.tombstoneTimeoutMs + this.sweepGracePeriodMs - unreferencedDurationMs,
+			);
+			return;
+		}
+
+		// If the node has been unreferenced for long enough, update the state to inactive.
+		// Also, start a timer for the remainder of the tombstone timeout.
 		if (unreferencedDurationMs >= this.inactiveTimeoutMs) {
 			this._state = UnreferencedState.Inactive;
-			this.inactiveTimer.clear();
 
-			if (this.sweepTimeoutMs !== undefined) {
-				this.sweepTimer.restart(this.sweepTimeoutMs - unreferencedDurationMs);
+			if (this.tombstoneTimeoutMs !== undefined) {
+				this.tombstoneTimer.restart(this.tombstoneTimeoutMs - unreferencedDurationMs);
 			}
 			return;
 		}
@@ -103,6 +141,7 @@ export class UnreferencedStateTracker {
 
 	private clearTimers() {
 		this.inactiveTimer.clear();
+		this.tombstoneTimer.clear();
 		this.sweepTimer.clear();
 	}
 

package/src/gc/index.ts

@@ -7,12 +7,12 @@ export { GarbageCollector } from "./garbageCollection";
 export {
 	nextGCVersion,
 	defaultInactiveTimeoutMs,
+	defaultSweepGracePeriodMs,
 	defaultSessionExpiryDurationMs,
 	GCNodeType,
 	gcTestModeKey,
-	gcTombstoneGenerationOptionName,
-	gcThrowOnTombstoneLoadOptionName,
-	gcSweepGenerationOptionName,
+	gcDisableThrowOnTombstoneLoadOptionName,
+	gcGenerationOptionName,
 	GCFeatureMatrix,
 	GCVersion,
 	gcVersionUpgradeToV4Key,
@@ -35,6 +35,7 @@ export {
 	disableDatastoreSweepKey,
 	UnreferencedState,
 	throwOnTombstoneLoadOverrideKey,
+	GarbageCollectionMessage,
 } from "./gcDefinitions";
 export {
 	cloneGCData,

package/src/index.ts

@@ -93,5 +93,21 @@ export {
 	IRetriableFailureResult,
 	ISummarizeEventProps,
 } from "./summary";
-export { isStableId, generateStableId, assertIsStableId } from "./id-compressor";
 export { IChunkedOp, unpackRuntimeMessage } from "./opLifecycle";
+
+// Re-exports for backwards compatibility.
+// Will be removed in the future.
+export {
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
+	assertIsStableId,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
+	generateStableId,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
+	isStableId,
+} from "@fluidframework/id-compressor";

package/src/messageTypes.ts

@@ -8,9 +8,10 @@ import {
 	IEnvelope,
 	InboundAttachMessage,
 	IAttachMessage,
-	IdCreationRange,
 } from "@fluidframework/runtime-definitions";
+import type { IdCreationRange } from "@fluidframework/id-compressor";
 import { IDataStoreAliasMessage } from "./dataStore";
+import { GarbageCollectionMessage } from "./gc";
 import { IChunkedOp } from "./opLifecycle";
 
 /**
@@ -41,6 +42,12 @@ export enum ContainerMessageType {
 	 * See the [IdCompressor README](./id-compressor/README.md) for more details.
 	 */
 	IdAllocation = "idAllocation",
+
+	/**
+	 * Garbage collection specific op. This is sent by the summarizer client when GC runs. It's used to synchronize GC
+	 * state across all clients.
+	 */
+	GC = "GC",
 }
 
 /**
@@ -120,6 +127,10 @@ export type ContainerRuntimeIdAllocationMessage = TypedContainerRuntimeMessage<
 	ContainerMessageType.IdAllocation,
 	IdCreationRange
 >;
+export type ContainerRuntimeGCMessage = TypedContainerRuntimeMessage<
+	ContainerMessageType.GC,
+	GarbageCollectionMessage
+>;
 
 /**
  * Represents an unrecognized {@link TypedContainerRuntimeMessage}, e.g. a message from a future version of the container runtime.
@@ -148,6 +159,7 @@ export type InboundContainerRuntimeMessage =
 	| ContainerRuntimeRejoinMessage
 	| ContainerRuntimeAliasMessage
 	| ContainerRuntimeIdAllocationMessage
+	| ContainerRuntimeGCMessage
 	// Inbound messages may include unknown types from other clients, so we include that as a special case here
 	| UnknownContainerRuntimeMessage;
 
@@ -160,6 +172,7 @@ export type LocalContainerRuntimeMessage =
 	| ContainerRuntimeRejoinMessage
 	| ContainerRuntimeAliasMessage
 	| ContainerRuntimeIdAllocationMessage
+	| ContainerRuntimeGCMessage
 	// In rare cases (e.g. related to stashed ops) we could have a local message of an unknown type
 	| UnknownContainerRuntimeMessage;
 
@@ -171,7 +184,8 @@ export type OutboundContainerRuntimeMessage =
 	| ContainerRuntimeBlobAttachMessage
 	| ContainerRuntimeRejoinMessage
 	| ContainerRuntimeAliasMessage
-	| ContainerRuntimeIdAllocationMessage;
+	| ContainerRuntimeIdAllocationMessage
+	| ContainerRuntimeGCMessage;
 
 /**
  * An unpacked ISequencedDocumentMessage with the inner TypedContainerRuntimeMessage type/contents/etc