[next] Driver Policy: Upcoming change notice for possible breaking change (#13787)

The policy `IDocumentStorageServicePolicies.maximumCacheDurationMs` MUST
be set and enforced by drivers
used in applications where [Garbage
Collection](/microsoft/fluidframework/tree/main/packages/runtime/container-runtime/garbageCollection.md)
is enabled, otherwise **data loss may occur**.

This PR updates the doc comments for the relevant interfaces, and also
adds an "Upcoming" note that this policy _may_ become required in a
later release.

BREAKING.md

@@ -19,10 +19,20 @@ It's important to communicate breaking changes to our stakeholders. To write a g
 
 ## 2.0.0-internal.3.0.0 Upcoming changes
 - [Deprecated IPendingFlush](#Deprecated-IPendingFlush)
+- [For Driver Authors: Document Storage Service policy may become required](#for-driver-authors-document-storage-service-policy-may-become-required)
 
 ### Deprecated IPendingFlush
 `IPendingFlush` has been deprecated. Use batch metadata on `IPendingMessage` instead to indicate the end of a batch.
 
+### For Driver Authors: Document Storage Service policy may become required
+
+_AWARENESS: The policy `IDocumentStorageServicePolicies.maximumCacheDurationMs` MUST be set and enforced by drivers
+used in applications where [Garbage Collection](packages/runtime/container-runtime/garbageCollection.md) is enabled, otherwise **data loss may occur**._
+
+In a subsequent major release, the policy `IDocumentStorageServicePolicies.maximumCacheDurationMs`
+(and likewise `IDocumentStorageService.policies` itself) may become required,
+to ensure all drivers take note of this requirement and enforce this policy.
+
 ## 2.0.0-internal.3.0.0 Breaking changes
 - [Existing flag is now required in IRuntimeFactory](#existing-parameter-is-now-required-in-iruntimefactory)
 - [Remove iframe-driver](#remove-iframe-driver)

api-report/driver-definitions.api.md

@@ -181,9 +181,8 @@ export interface IDocumentStorageService extends Partial<IDisposable> {
     uploadSummaryWithContext(summary: ISummaryTree, context: ISummaryContext): Promise<string>;
 }
 
-// @public (undocumented)
+// @public
 export interface IDocumentStorageServicePolicies {
-    // (undocumented)
     readonly caching?: LoaderCachingPolicy;
     readonly maximumCacheDurationMs?: FiveDaysMs;
     readonly minBlobSize?: number;

packages/common/driver-definitions/src/storage.ts

@@ -92,10 +92,20 @@ export interface IDocumentDeltaStorageService {
     ): IStream<ISequencedDocumentMessage[]>;
 }
 
-// DO NOT INCREASE THIS TYPE'S VALUE - If a driver started using a larger value, GC would likely start closing sessions
+// DO NOT INCREASE THIS TYPE'S VALUE
+// If a driver started using a larger value,
+// internal assumptions of the Runtime's GC feature will be violated
+// DO NOT INCREASE THIS TYPE'S VALUE
 export type FiveDaysMs = 432_000_000; /* 5 days in milliseconds */
 
+/**
+ * Policies describing attributes or characteristics of the driver's storage service,
+ * to direct how other components interact with the driver
+ */
 export interface IDocumentStorageServicePolicies {
+    /**
+     * Should the Loader implement any sort of pre-fetching or caching mechanism?
+     */
     readonly caching?: LoaderCachingPolicy;
 
     /**
@@ -105,10 +115,12 @@ export interface IDocumentStorageServicePolicies {
     readonly minBlobSize?: number;
 
     /**
+     * IMPORTANT: This policy MUST be set to 5 days and PROPERLY ENFORCED for drivers that are used
+     * in applications where Garbage Collection is enabled. Otherwise data loss may occur.
+     *
+     * This policy pertains to requests for the latest snapshot from the service.
+     * If set, it means that the driver guarantees not to use a cached value that was fetched more than 5 days ago.
      * If undefined, the driver makes no guarantees about the age of snapshots used for loading.
-     * Otherwise, the driver will not use snapshots that were added to the cache more than 5 days ago (per client clock)
-     * The value MUST be 5 days if defined. This fixed upper bound is necessary for the Garbage Collection feature
-     * in the Runtime layer to reliably compute when an object will never be referenced again and can be deleted.
      */
     readonly maximumCacheDurationMs?: FiveDaysMs;
 }