@fluidframework/container-runtime 2.0.0-dev.3.1.0.125672 → 2.0.0-dev.4.2.0.153917

package/src/gc/gcConfigs.ts

@@ -0,0 +1,193 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UsageError } from "@fluidframework/container-utils";
+import { MonitoringContext } from "@fluidframework/telemetry-utils";
+import { IContainerRuntimeMetadata } from "../summary";
+import {
+	currentGCVersion,
+	defaultInactiveTimeoutMs,
+	defaultSessionExpiryDurationMs,
+	disableTombstoneKey,
+	GCFeatureMatrix,
+	gcSweepGenerationOptionName,
+	gcTestModeKey,
+	gcTombstoneGenerationOptionName,
+	GCVersion,
+	gcVersionUpgradeToV3Key,
+	IGarbageCollectorConfigs,
+	IGCRuntimeOptions,
+	maxSnapshotCacheExpiryMs,
+	oneDayMs,
+	runGCKey,
+	runSessionExpiryKey,
+	runSweepKey,
+	stableGCVersion,
+} from "./gcDefinitions";
+import { getGCVersion, shouldAllowGcSweep } from "./gcHelpers";
+
+/**
+ * Generates configurations for the Garbage Collector that it uses to determine what to run and how.
+ * @param mc - The monitoring context for reading configs from the config provider.
+ * @param createParams - The creation params:
+ * gcOptions - The garbage collector runtime options.
+ * metadata - The container runtime's createParams.metadata.
+ * existing - Whether the container is new or an existing one.
+ * @returns The garbage collector configurations.
+ */
+export function generateGCConfigs(
+	mc: MonitoringContext,
+	createParams: {
+		gcOptions: IGCRuntimeOptions;
+		metadata: IContainerRuntimeMetadata | undefined;
+		existing: boolean;
+	},
+): IGarbageCollectorConfigs {
+	let gcEnabled: boolean;
+	let sessionExpiryTimeoutMs: number | undefined;
+	let sweepTimeoutMs: number | undefined;
+	let persistedGcFeatureMatrix: GCFeatureMatrix | undefined;
+	let gcVersionInBaseSnapshot: GCVersion | undefined;
+
+	/**
+	 * The following GC state is enabled during container creation and cannot be changed throughout its lifetime:
+	 * 1. Whether running GC mark phase is allowed or not.
+	 * 2. Whether running GC sweep phase is allowed or not.
+	 * 3. Whether GC session expiry is enabled or not.
+	 * For existing containers, we get this information from the createParams.metadata blob of its summary.
+	 */
+	if (createParams.existing) {
+		gcVersionInBaseSnapshot = getGCVersion(createParams.metadata);
+		// Existing documents which did not have createParams.metadata blob or had GC disabled have version as 0. For all
+		// other existing documents, GC is enabled.
+		gcEnabled = gcVersionInBaseSnapshot > 0;
+		sessionExpiryTimeoutMs = createParams.metadata?.sessionExpiryTimeoutMs;
+		sweepTimeoutMs =
+			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",
+		);
+
+		// For new documents, GC is enabled by default. It can be explicitly disabled by setting the gcAllowed
+		// flag in GC options to false.
+		gcEnabled = createParams.gcOptions.gcAllowed !== false;
+
+		// Set the Session Expiry if GC is enabled and session expiry flag isn't explicitly set to false.
+		if (gcEnabled && mc.config.getBoolean(runSessionExpiryKey) !== false) {
+			sessionExpiryTimeoutMs =
+				createParams.gcOptions.sessionExpiryTimeoutMs ?? defaultSessionExpiryDurationMs;
+		}
+		sweepTimeoutMs = testOverrideSweepTimeoutMs ?? computeSweepTimeout(sessionExpiryTimeoutMs);
+
+		if (tombstoneGeneration !== undefined || sweepGeneration !== undefined) {
+			persistedGcFeatureMatrix = {
+				tombstoneGeneration,
+				sweepGeneration,
+			};
+		}
+	}
+
+	// Is sweepEnabled for this document?
+	const sweepEnabled = shouldAllowGcSweep(
+		persistedGcFeatureMatrix ?? {} /* persistedGenerations */,
+		createParams.gcOptions[gcSweepGenerationOptionName] /* currentGeneration */,
+	);
+
+	/**
+	 * 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.
+	 *
+	 * These conditions can be overridden via runGCKey feature flag.
+	 */
+	const shouldRunGC =
+		mc.config.getBoolean(runGCKey) ??
+		// GC must be enabled for the document.
+		(gcEnabled &&
+			// GC must not be disabled via GC options.
+			!createParams.gcOptions.disableGC);
+
+	/**
+	 * Whether sweep should run or not. The following conditions have to be met to run sweep:
+	 *
+	 * 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.
+	 */
+	const shouldRunSweep =
+		shouldRunGC &&
+		sweepTimeoutMs !== undefined &&
+		(mc.config.getBoolean(runSweepKey) ?? sweepEnabled);
+
+	// Override inactive timeout if test config or gc options to override it is set.
+	const inactiveTimeoutMs =
+		mc.config.getNumber("Fluid.GarbageCollection.TestOverride.InactiveTimeoutMs") ??
+		createParams.gcOptions.inactiveTimeoutMs ??
+		defaultInactiveTimeoutMs;
+
+	// Inactive timeout must be greater than sweep timeout since a node goes from active -> inactive -> sweep ready.
+	if (sweepTimeoutMs !== undefined && inactiveTimeoutMs > sweepTimeoutMs) {
+		throw new UsageError("inactive timeout should not be greater than the sweep timeout");
+	}
+
+	// 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;
+	const runFullGC = createParams.gcOptions.runFullGC;
+
+	// If version upgrade is not enabled, fall back to the stable GC version.
+	const gcVersionInEffect =
+		mc.config.getBoolean(gcVersionUpgradeToV3Key) === false
+			? stableGCVersion
+			: currentGCVersion;
+
+	return {
+		gcEnabled,
+		sweepEnabled,
+		shouldRunGC,
+		shouldRunSweep,
+		runFullGC,
+		testMode,
+		tombstoneMode,
+		sessionExpiryTimeoutMs,
+		sweepTimeoutMs,
+		inactiveTimeoutMs,
+		persistedGcFeatureMatrix,
+		gcVersionInBaseSnapshot,
+		gcVersionInEffect,
+	};
+}
+
+/**
+ * Sweep timeout is the time after which unreferenced content can be swept.
+ * Sweep timeout = session expiry timeout + snapshot cache expiry timeout + one day buffer.
+ *
+ * The snapshot cache expiry timeout cannot be known precisely but the upper bound is 5 days.
+ * The buffer is added to account for any clock skew or other edge cases.
+ * We use server timestamps throughout so the skew should be minimal but make it 1 day to be safe.
+ */
+function computeSweepTimeout(sessionExpiryTimeoutMs: number | undefined): number | undefined {
+	const bufferMs = oneDayMs;
+	return sessionExpiryTimeoutMs && sessionExpiryTimeoutMs + maxSnapshotCacheExpiryMs + bufferMs;
+}

package/src/gc/gcDefinitions.ts

@@ -0,0 +1,387 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ICriticalContainerError } from "@fluidframework/container-definitions";
+import { IRequestHeader } from "@fluidframework/core-interfaces";
+import { ISnapshotTree } from "@fluidframework/protocol-definitions";
+import {
+	IGarbageCollectionData,
+	IGarbageCollectionDetailsBase,
+	ISummarizeResult,
+	ITelemetryContext,
+} from "@fluidframework/runtime-definitions";
+import { ReadAndParseBlob } from "@fluidframework/runtime-utils";
+import { ITelemetryLogger } from "@fluidframework/common-definitions";
+import {
+	IContainerRuntimeMetadata,
+	ICreateContainerMetadata,
+	RefreshSummaryResult,
+} from "../summary";
+
+export type GCVersion = number;
+
+/** The stable version of garbage collection in production. */
+export const stableGCVersion: GCVersion = 1;
+/** The current version of garbage collection. */
+export const currentGCVersion: GCVersion = 3;
+
+/**
+ * This undocumented GC Option (on ContainerRuntime Options) allows an app to disable enforcing GC on old documents by incrementing this value
+ *
+ * If unset, GC Tombstone phase will operate as otherwise configured
+ * Otherwise, only enforce GC Tombstone if the passed in value matches the persisted value
+ */
+export const gcTombstoneGenerationOptionName = "gcTombstoneGeneration";
+/**
+ * This GC Option (on ContainerRuntime Options) allows an app to disable GC Sweep on old documents by incrementing this value.
+ *
+ * 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.
+ */
+export const gcSweepGenerationOptionName = "gcSweepGeneration";
+
+// Feature gate key to turn GC on / off.
+export const runGCKey = "Fluid.GarbageCollection.RunGC";
+// Feature gate key to turn GC sweep on / off.
+export const runSweepKey = "Fluid.GarbageCollection.RunSweep";
+// Feature gate key to turn GC test mode on / off.
+export const gcTestModeKey = "Fluid.GarbageCollection.GCTestMode";
+// Feature gate key to expire a session after a set period of time.
+export const runSessionExpiryKey = "Fluid.GarbageCollection.RunSessionExpiry";
+// Feature gate key to turn GC sweep log off.
+export const disableSweepLogKey = "Fluid.GarbageCollection.DisableSweepLog";
+// Feature gate key to disable the tombstone feature, i.e., tombstone information is not read / written into summary.
+export const disableTombstoneKey = "Fluid.GarbageCollection.DisableTombstone";
+// Feature gate to enable throwing an error when tombstone object is loaded (requested).
+export const throwOnTombstoneLoadKey = "Fluid.GarbageCollection.ThrowOnTombstoneLoad";
+// Feature gate to enable throwing an error when tombstone object is used (e.g. outgoing or incoming ops).
+export const throwOnTombstoneUsageKey = "Fluid.GarbageCollection.ThrowOnTombstoneUsage";
+// Feature gate to enable GC version upgrade.
+export const gcVersionUpgradeToV3Key = "Fluid.GarbageCollection.GCVersionUpgradeToV3";
+// Feature gate to enable GC sweep for datastores.
+// TODO: Remove Test from the flag when we are confident to turn on sweep
+export const sweepDatastoresKey = "Fluid.GarbageCollection.Test.SweepDataStores";
+// Feature gate to enable GC sweep for attachment blobs.
+export const sweepAttachmentBlobsKey = "Fluid.GarbageCollection.Test.SweepAttachmentBlobs";
+
+// One day in milliseconds.
+export const oneDayMs = 1 * 24 * 60 * 60 * 1000;
+
+/**
+ * The maximum snapshot cache expiry in the driver. This is used to calculate the sweep timeout.
+ * Sweep timeout = session expiry timeout + snapshot cache expiry timeout + a buffer.
+ * The snapshot cache expiry timeout cannot be known precisely but the upper bound is 5 days, i.e., any snapshot
+ * in cache will be invalidated before 5 days.
+ */
+export const maxSnapshotCacheExpiryMs = 5 * oneDayMs;
+
+export const defaultInactiveTimeoutMs = 7 * oneDayMs; // 7 days
+export const defaultSessionExpiryDurationMs = 30 * oneDayMs; // 30 days
+
+/** @see IGCMetadata.gcFeatureMatrix */
+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 interface IGCMetadata {
+	/**
+	 * The version of the GC code that was run to generate the GC data that is written in the summary.
+	 * If the persisted value doesn't match the current value in the code, saved GC data will be discarded and regenerated from scratch.
+	 * Also, used to determine whether GC is enabled for this container or not:
+	 * - A value of 0 or undefined means GC is disabled.
+	 * - A value greater than 0 means GC is enabled.
+	 */
+	readonly gcFeature?: GCVersion;
+
+	/**
+	 * A collection of different numerical "Generations" for different features,
+	 * used to determine feature availability over time.
+	 * This info may come from multiple sources (FF code, config service, app via Container Runtime Options),
+	 * and pertains to aspects of the document that may be fixed for its lifetime.
+	 *
+	 * For each dimension, if the persisted value doesn't match the currently provided value,
+	 * then this file does not support the corresponding feature as currently implemented.
+	 *
+	 * Guidance is that if no value is provided at runtime, it should result in the current default behavior.
+	 */
+	readonly gcFeatureMatrix?: GCFeatureMatrix;
+	/**
+	 * @deprecated - @see GCFeatureMatrix.sweepGeneration
+	 *
+	 * Tells whether the GC sweep phase is enabled for this container.
+	 * - True means sweep phase is enabled.
+	 * - False means sweep phase is disabled. If GC is disabled as per gcFeature, sweep is also disabled.
+	 */
+	readonly sweepEnabled?: boolean;
+	/** If this is present, the session for this container will expire after this time and the container will close */
+	readonly sessionExpiryTimeoutMs?: number;
+	/** How long to wait after an object is unreferenced before deleting it via GC Sweep */
+	readonly sweepTimeoutMs?: number;
+}
+
+/** The statistics of the system state after a garbage collection run. */
+export interface IGCStats {
+	/** The number of nodes in the container. */
+	nodeCount: number;
+	/** The number of data stores in the container. */
+	dataStoreCount: number;
+	/** The number of attachment blobs in the container. */
+	attachmentBlobCount: number;
+	/** The number of unreferenced nodes in the container. */
+	unrefNodeCount: number;
+	/** The number of unreferenced data stores in the container. */
+	unrefDataStoreCount: number;
+	/** The number of unreferenced attachment blobs in the container. */
+	unrefAttachmentBlobCount: number;
+	/** The number of nodes whose reference state updated since last GC run. */
+	updatedNodeCount: number;
+	/** The number of data stores whose reference state updated since last GC run. */
+	updatedDataStoreCount: number;
+	/** The number of attachment blobs whose reference state updated since last GC run. */
+	updatedAttachmentBlobCount: number;
+}
+
+/** The types of GC nodes in the GC reference graph. */
+export const GCNodeType = {
+	// Nodes that are for data stores.
+	DataStore: "DataStore",
+	// Nodes that are within a data store. For example, DDS nodes.
+	SubDataStore: "SubDataStore",
+	// Nodes that are for attachment blobs, i.e., blobs uploaded via BlobManager.
+	Blob: "Blob",
+	// Nodes that are neither of the above. For example, root node.
+	Other: "Other",
+};
+export type GCNodeType = typeof GCNodeType[keyof typeof GCNodeType];
+
+/**
+ * Defines the APIs for the runtime object to be passed to the garbage collector.
+ */
+export interface IGarbageCollectionRuntime {
+	/** Before GC runs, called to notify the runtime to update any pending GC state. */
+	updateStateBeforeGC(): Promise<void>;
+	/** 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;
+	/** After GC has run, called to notify the runtime of routes that are unused in it. */
+	updateUnusedRoutes(unusedRoutes: 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[];
+	/** Called to notify the runtime of routes that are tombstones. */
+	updateTombstonedRoutes(tombstoneRoutes: string[]): void;
+	/** Returns a referenced timestamp to be used to track unreferenced nodes. */
+	getCurrentReferenceTimestampMs(): number | undefined;
+	/** Returns the type of the GC node. */
+	getNodeType(nodePath: string): GCNodeType;
+	/** Called when the runtime should close because of an error. */
+	closeFn: (error?: ICriticalContainerError) => void;
+	/** If false, loading or using a Tombstoned object should merely log, not fail */
+	gcTombstoneEnforcementAllowed: boolean;
+}
+
+/** Defines the contract for the garbage collector. */
+export interface IGarbageCollector {
+	/** Tells whether GC should run or not. */
+	readonly shouldRunGC: boolean;
+	/** Tells whether the GC state in summary needs to be reset in the next summary. */
+	readonly summaryStateNeedsReset: boolean;
+	/** Initialize the state from the base snapshot after its creation. */
+	initializeBaseState(): Promise<void>;
+	/** Run garbage collection and update the reference / used state of the system. */
+	collectGarbage(
+		options: {
+			logger?: ITelemetryLogger;
+			runSweep?: boolean;
+			fullGC?: boolean;
+		},
+		telemetryContext?: ITelemetryContext,
+	): Promise<IGCStats | undefined>;
+	/** Summarizes the GC data and returns it as a summary tree. */
+	summarize(
+		fullTree: boolean,
+		trackState: boolean,
+		telemetryContext?: ITelemetryContext,
+	): ISummarizeResult | undefined;
+	/** Returns the garbage collector specific metadata to be written into the summary. */
+	getMetadata(): IGCMetadata;
+	/** Returns the GC details generated from the base snapshot. */
+	getBaseGCDetails(): Promise<IGarbageCollectionDetailsBase>;
+	/** Called when the latest summary of the system has been refreshed. */
+	refreshLatestSummary(
+		proposalHandle: string | undefined,
+		result: RefreshSummaryResult,
+		readAndParseBlob: ReadAndParseBlob,
+	): Promise<void>;
+	/** Called when a node is updated. Used to detect and log when an inactive node is changed or loaded. */
+	nodeUpdated(
+		nodePath: string,
+		reason: "Loaded" | "Changed",
+		timestampMs?: number,
+		packagePath?: readonly string[],
+		requestHeaders?: IRequestHeader,
+	): 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;
+	/** Returns true if this node has been deleted by GC during sweep phase. */
+	isNodeDeleted(nodePath: string): boolean;
+	setConnectionState(connected: boolean, clientId?: string): void;
+	dispose(): void;
+}
+
+/** Parameters necessary for creating a GarbageCollector. */
+export interface IGarbageCollectorCreateParams {
+	readonly runtime: IGarbageCollectionRuntime;
+	readonly gcOptions: IGCRuntimeOptions;
+	readonly baseLogger: ITelemetryLogger;
+	readonly existing: boolean;
+	readonly metadata: IContainerRuntimeMetadata | undefined;
+	readonly createContainerMetadata: ICreateContainerMetadata;
+	readonly baseSnapshot: ISnapshotTree | undefined;
+	readonly isSummarizerClient: boolean;
+	readonly getNodePackagePath: (nodePath: string) => Promise<readonly string[] | undefined>;
+	readonly getLastSummaryTimestampMs: () => number | undefined;
+	readonly readAndParseBlob: ReadAndParseBlob;
+	readonly activeConnection: () => boolean;
+	readonly getContainerDiagnosticId: () => string;
+}
+
+export interface IGCRuntimeOptions {
+	/**
+	 * Flag that if true, will enable running garbage collection (GC) for a new container.
+	 *
+	 * 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 via the "sweepAllowed" option.
+	 *
+	 * Note: This setting is persisted in the container's summary and cannot be changed.
+	 */
+	gcAllowed?: boolean;
+
+	/**
+	 * @deprecated -  @see gcSweepGenerationOptionName and @see GCFeatureMatrix.sweepGeneration
+	 *
+	 * Flag that if true, enables GC's sweep phase for a new container.
+	 *
+	 * This will allow GC to eventually delete unreferenced objects from the container.
+	 * This flag should only be set to true if "gcAllowed" is true.
+	 *
+	 * Note: This setting is persisted in the container's summary and cannot be changed.
+	 */
+	sweepAllowed?: boolean;
+
+	/**
+	 * Flag that if true, will disable garbage collection for the session.
+	 * Can be used to disable running GC on containers where it is allowed via the gcAllowed option.
+	 */
+	disableGC?: boolean;
+
+	/**
+	 * Flag that will bypass optimizations and generate GC data for all nodes irrespective of whether a node
+	 * changed or not.
+	 */
+	runFullGC?: boolean;
+
+	/**
+	 * Maximum session duration for a new container. If not present, a default value will be used.
+	 *
+	 * Note: This setting is persisted in the container's summary and cannot be changed.
+	 */
+	sessionExpiryTimeoutMs?: number;
+
+	/**
+	 * Allows additional GC options to be passed.
+	 */
+	[key: string]: any;
+}
+
+/**
+ * The configurations for Garbage Collector that determines what runs and how.
+ */
+export interface IGarbageCollectorConfigs {
+	/**
+	 * Tracks if GC is enabled for this document. This is specified during document creation and doesn't change
+	 * throughout its lifetime.
+	 */
+	readonly gcEnabled: boolean;
+	/**
+	 * Tracks if sweep phase is enabled for this document. This is specified during document creation and doesn't change
+	 * throughout its lifetime.
+	 */
+	readonly sweepEnabled: boolean;
+	/**
+	 * Tracks if GC should run or not. Even if GC is enabled for a document (see gcEnabled), it can be explicitly
+	 * disabled via runtime options or feature flags.
+	 */
+	readonly shouldRunGC: boolean;
+	/**
+	 * Tracks if sweep phase should run or not. Even if the sweep phase is enabled for a document (see sweepEnabled), it
+	 * can be explicitly disabled via feature flags. It also won't run if session expiry is not enabled.
+	 */
+	readonly shouldRunSweep: boolean;
+	/**
+	 * If true, bypass optimizations and generate GC data for all nodes irrespective of whether a node changed or not.
+	 */
+	readonly runFullGC: boolean | undefined;
+	/** The time in ms to expire a session for a client for gc. */
+	readonly sessionExpiryTimeoutMs: number | undefined;
+	/** The time after which an unreferenced node is ready to be swept. */
+	readonly sweepTimeoutMs: number | undefined;
+	/** 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.
+	 * 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.
+	 */
+	readonly tombstoneMode: boolean;
+	/** @see GCFeatureMatrix. */
+	readonly persistedGcFeatureMatrix: GCFeatureMatrix | undefined;
+	/** The version of GC in the base snapshot. */
+	readonly gcVersionInBaseSnapshot: GCVersion | undefined;
+	/** The current version of GC data in the running code */
+	readonly gcVersionInEffect: GCVersion;
+}
+
+/** The state of node that is unreferenced. */
+export const UnreferencedState = {
+	/** The node is active, i.e., it can become referenced again. */
+	Active: "Active",
+	/** The node is inactive, i.e., it should not become referenced. */
+	Inactive: "Inactive",
+	/** The node is ready to be deleted by the sweep phase. */
+	SweepReady: "SweepReady",
+} as const;
+export type UnreferencedState = typeof UnreferencedState[keyof typeof UnreferencedState];
+
+/**
+ * Represents the result of a GC run.
+ */
+export interface IGCResult {
+	/** The ids of nodes that are referenced in the referenced graph */
+	referencedNodeIds: string[];
+	/** The ids of nodes that are not-referenced or deleted in the referenced graph */
+	deletedNodeIds: string[];
+}