@fluidframework/container-runtime 2.0.0-internal.7.2.2 → 2.0.0-internal.7.4.0

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,
 	};

package/src/gc/gcDefinitions.ts

@@ -20,9 +20,10 @@ import {
 	IRefreshSummaryResult,
 } from "../summary";
 import { RuntimeHeaderData } from "../containerRuntime";
+import { ContainerRuntimeGCMessage } from "../messageTypes";
 
 /**
- * @public
+ * @alpha
  */
 export type GCVersion = number;
 
@@ -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";
@@ -62,8 +61,6 @@ export const runSweepKey = "Fluid.GarbageCollection.RunSweep";
 export const gcTestModeKey = "Fluid.GarbageCollection.GCTestMode";
 /** Config key to expire a session after a set period of time. Defaults to true. */
 export const runSessionExpiryKey = "Fluid.GarbageCollection.RunSessionExpiry";
-/** Config key to turn GC sweep log off. */
-export const disableSweepLogKey = "Fluid.GarbageCollection.DisableSweepLog";
 /** Config key to disable the tombstone feature, i.e., tombstone information is not read / written into summary. */
 export const disableTombstoneKey = "Fluid.GarbageCollection.DisableTombstone";
 /** Config key to override throwing an error when tombstone object is loaded (requested). */
@@ -91,28 +88,33 @@ 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
- * @public
+ * @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;
+	  };
 
 /**
- * @public
+ * @alpha
  */
 export interface IGCMetadata {
 	/**
@@ -141,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 */
@@ -151,10 +153,10 @@ export interface IGCMetadata {
 }
 
 /**
- * The statistics of the system state after a garbage collection run.
- * @public
+ * The statistics of the system state after a garbage collection mark phase run.
+ * @alpha
  */
-export interface IGCStats {
+export interface IMarkPhaseStats {
 	/** The number of nodes in the container. */
 	nodeCount: number;
 	/** The number of data stores in the container. */
@@ -175,9 +177,34 @@ export interface IGCStats {
 	updatedAttachmentBlobCount: number;
 }
 
+/**
+ * The statistics of the system state after a garbage collection sweep phase run.
+ * @alpha
+ */
+export interface ISweepPhaseStats {
+	/** The number of nodes in the lifetime of the container. */
+	lifetimeNodeCount: number;
+	/** The number of data stores in the lifetime of the container. */
+	lifetimeDataStoreCount: number;
+	/** The number of attachment blobs in the lifetime of the container. */
+	lifetimeAttachmentBlobCount: number;
+	/** The number of deleted nodes in the container. */
+	deletedNodeCount: number;
+	/** The number of deleted data stores in the container. */
+	deletedDataStoreCount: number;
+	/** The number of deleted attachment blobs in the container. */
+	deletedAttachmentBlobCount: number;
+}
+
+/**
+ * The statistics of the system state after a garbage collection run.
+ * @alpha
+ */
+export interface IGCStats extends IMarkPhaseStats, ISweepPhaseStats {}
+
 /**
  * The types of GC nodes in the GC reference graph.
- * @public
+ * @alpha
  */
 export const GCNodeType = {
 	// Nodes that are for data stores.
@@ -191,10 +218,41 @@ export const GCNodeType = {
 };
 
 /**
- * @public
+ * @alpha
  */
 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.
  */
@@ -204,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. */
@@ -274,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;
@@ -294,10 +354,11 @@ export interface IGarbageCollectorCreateParams {
 	readonly getLastSummaryTimestampMs: () => number | undefined;
 	readonly readAndParseBlob: ReadAndParseBlob;
 	readonly activeConnection: () => boolean;
+	readonly submitMessage: (message: ContainerRuntimeGCMessage) => void;
 }
 
 /**
- * @public
+ * @alpha
  */
 export interface IGCRuntimeOptions {
 	/**
@@ -306,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.
 	 */
@@ -318,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.
@@ -331,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.
 	 */
@@ -369,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. */
@@ -388,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. */
@@ -402,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";
+}