improvement(runtime): Add fail fast mechanism for runtime options that require explicitSchemaControl (microsoft#25430)

## Description

This PR adds a fail fast mechanism that will throw a `UsageError` if a
runtime option that requires `explicitSchemaControl` is enabled without
enabling `explicitSchemaControl` as well.

To avoid disruption for existing customers, we will only apply this to
runtime options that were added after `explicitSchemaControl` was
introduced. Currently, this only applies to `createBlobPayloadPending`,
but going forward FF devs will be required to add new runtime options to
`runtimeOptionKeysThatRequireExplicitSchemaControl` (the build will not
compile otherwise). This will enforce this fail fast mechanism for any
new runtime options going forward.

## Misc

[AB#48150](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/48150)

---------

Co-authored-by: Matt Rakow <ChumpChief@users.noreply.github.com>

Author: scottn12

packages/runtime/container-runtime/src/containerCompatibility.ts

@@ -45,6 +45,49 @@ export type RuntimeOptionsAffectingDocSchema = Omit<
 	| "summaryOptions"
 >;
 
+/**
+ * Subset of {@link RuntimeOptionsAffectingDocSchema} which existed prior to the introduction of explicitSchemaControl.
+ *
+ * @remarks
+ * Runtime options that affect document schema should generally require explicitSchemaControl to be enabled.
+ * However, to prevent disruption to existing customers, options that existed prior to explicitSchemaControl
+ * do not explicity require explicitSchemaControl to be enabled. Do not add new options to this list.
+ */
+type RuntimeOptionKeysPredatingExplicitSchemaControl = keyof Pick<
+	RuntimeOptionsAffectingDocSchema,
+	| "explicitSchemaControl"
+	| "compressionOptions"
+	| "enableRuntimeIdCompressor"
+	| "flushMode"
+	| "gcOptions"
+	| "enableGroupedBatching"
+>;
+
+/**
+ * List of keys of {@link RuntimeOptionsAffectingDocSchema} which existed prior to the introduction of explicitSchemaControl.
+ *
+ * @remarks
+ * Runtime options that affect document schema should generally require explicitSchemaControl to be enabled.
+ * However, to prevent disruption to existing customers, options that existed prior to explicitSchemaControl
+ * do not explicity require explicitSchemaControl to be enabled. Do not add new keys to this list.
+ */
+const keysOfOptionsPredatingExplicitSchemaControl = new Set([
+	"explicitSchemaControl",
+	"compressionOptions",
+	"enableRuntimeIdCompressor",
+	"flushMode",
+	"gcOptions",
+	"enableGroupedBatching",
+]) satisfies Set<RuntimeOptionKeysPredatingExplicitSchemaControl>;
+
+/**
+ * Subset of {@link RuntimeOptionsAffectingDocSchema} which require explicitSchemaControl to be enabled.
+ */
+export type RuntimeOptionKeysThatRequireExplicitSchemaControl = keyof Omit<
+	RuntimeOptionsAffectingDocSchema,
+	RuntimeOptionKeysPredatingExplicitSchemaControl
+>;
+
 /**
  * Mapping of RuntimeOptionsAffectingDocSchema to their compatibility related configs.
  *
@@ -113,6 +156,19 @@ const runtimeOptionsAffectingDocSchemaConfigMap = {
 	},
 } as const satisfies ConfigMap<RuntimeOptionsAffectingDocSchema>;
 
+/**
+ * Keys of {@link ContainerRuntimeOptionsInternal} that require explicitSchemaControl to be enabled.
+ */
+export const runtimeOptionKeysThatRequireExplicitSchemaControl = (
+	Object.keys(
+		runtimeOptionsAffectingDocSchemaConfigMap,
+	) as (keyof RuntimeOptionsAffectingDocSchema)[]
+).filter((key) => {
+	return !keysOfOptionsPredatingExplicitSchemaControl.has(
+		key as RuntimeOptionKeysPredatingExplicitSchemaControl,
+	);
+}) as RuntimeOptionKeysThatRequireExplicitSchemaControl[];
+
 const runtimeOptionsAffectingDocSchemaConfigValidationMap = {
 	enableGroupedBatching: configValueToMinVersionForCollab([
 		[false, "1.0.0"],

packages/runtime/container-runtime/src/containerRuntime.ts

@@ -195,6 +195,8 @@ import {
 	getMinVersionForCollabDefaults,
 	type RuntimeOptionsAffectingDocSchema,
 	validateRuntimeOptions,
+	runtimeOptionKeysThatRequireExplicitSchemaControl,
+	type RuntimeOptionKeysThatRequireExplicitSchemaControl,
 } from "./containerCompatibility.js";
 import { ContainerFluidHandleContext } from "./containerHandleContext.js";
 import { channelToDataStore } from "./dataStore.js";
@@ -947,6 +949,19 @@ export class ContainerRuntime
 			createBlobPayloadPending = defaultConfigs.createBlobPayloadPending,
 		}: IContainerRuntimeOptionsInternal = runtimeOptions;
 
+		// If explicitSchemaControl is off, ensure that options which require explicitSchemaControl are not enabled.
+		if (!explicitSchemaControl) {
+			const disallowedKeys = Object.keys(runtimeOptions).filter(
+				(key) =>
+					runtimeOptionKeysThatRequireExplicitSchemaControl.includes(
+						key as RuntimeOptionKeysThatRequireExplicitSchemaControl,
+					) && runtimeOptions[key] !== undefined,
+			);
+			if (disallowedKeys.length > 0) {
+				throw new UsageError(`explicitSchemaControl must be enabled to use ${disallowedKeys}`);
+			}
+		}
+
 		// The logic for enableRuntimeIdCompressor is a bit different. Since `undefined` represents a logical state (off)
 		// we need to check it's explicitly set in runtimeOptions. If so, we should use that value even if it's undefined.
 		const enableRuntimeIdCompressor =

packages/runtime/container-runtime/src/test/containerRuntime.spec.ts

@@ -3739,6 +3739,29 @@ describe("Runtime", () => {
 						"Container should throw when op compression is on and op grouping is off",
 					);
 				});
+
+				it("Throws when createBlobPayloadPending is on and explicitSchemaControl is not enabled", async () => {
+					await assert.rejects(
+						async () =>
+							ContainerRuntime.loadRuntime({
+								context: getMockContext() as IContainerContext,
+								registryEntries: [],
+								existing: false,
+								runtimeOptions: {
+									createBlobPayloadPending: true,
+								},
+								provideEntryPoint: mockProvideEntryPoint,
+							}),
+						(error: IErrorBase) => {
+							return (
+								error.errorType === ContainerErrorTypes.usageError &&
+								error.message ===
+									"explicitSchemaControl must be enabled to use createBlobPayloadPending"
+							);
+						},
+						"Container should throw when createBlobPayloadPending is on and explicitSchemaControl is not enabled",
+					);
+				});
 			});
 		});
 
@@ -4134,7 +4157,7 @@ describe("Runtime", () => {
 						existing: false,
 						// We would normally throw (since `createBlobPayloadPending` requires 2.40), but since we did
 						// not explicity set minVersionForCollab, we allow it.
-						runtimeOptions: { createBlobPayloadPending: true },
+						runtimeOptions: { createBlobPayloadPending: true, explicitSchemaControl: true },
 						provideEntryPoint: mockProvideEntryPoint,
 					});
 				});

packages/test/local-server-stress-tests/src/stressDataObject.ts

@@ -355,6 +355,7 @@ export const createRuntimeFactory = (): IRuntimeFactory => {
 		},
 		enableRuntimeIdCompressor: "on",
 		createBlobPayloadPending: true,
+		explicitSchemaControl: true,
 	};
 
 	return {

packages/test/test-end-to-end-tests/src/test/blobsisAttached.spec.ts

@@ -52,6 +52,7 @@ for (const createBlobPayloadPending of [undefined, true] as const) {
 				fluidDataObjectType: DataObjectFactoryType.Test,
 				registry,
 				runtimeOptions: {
+					explicitSchemaControl: true,
 					createBlobPayloadPending,
 				},
 			};

packages/test/test-service-load/src/optionsMatrix.ts

@@ -141,6 +141,18 @@ export function generateRuntimeOptions(
 		}
 	});
 
+	// Override explicitSchemaControl to enabled if createBlobPayloadPending is enabled
+	pairwiseOptions.map((options) => {
+		if (options.createBlobPayloadPending) {
+			(
+				options as {
+					// Remove readonly modifier to allow overriding
+					-readonly [P in keyof ContainerRuntimeOptionsInternal]: ContainerRuntimeOptionsInternal[P];
+				}
+			).explicitSchemaControl = true;
+		}
+	});
+
 	return pairwiseOptions;
 }