feat(container-runtime): allow createBlobPayloadPending to be explicitly set to false

.changeset/shaky-queens-bake.md

@@ -0,0 +1,8 @@
+---
+"@fluidframework/container-runtime": minor
+"__section": feature
+---
+
+`createBlobPayloadPending` runtime option now accepts `false`
+
+The `createBlobPayloadPending` property on `ContainerRuntimeOptions` (`@legacy @beta`) now has type `boolean | undefined` instead of `true | undefined`, allowing consumers to explicitly pass `false` to disable the feature. Passing `false` behaves the same as leaving the option `undefined` (disabled); this is a non-breaking, backwards-compatible widening of the accepted type.

packages/framework/aqueduct/package.json

@@ -153,6 +153,9 @@
 	},
 	"typeValidation": {
 		"broken": {
+			"Interface_ContainerRuntimeFactoryWithDefaultDataStoreProps": {
+				"backCompat": false
+			},
 			"Interface_DataObjectFactoryProps": {
 				"backCompat": false
 			},

packages/framework/aqueduct/src/test/types/validateAqueductPrevious.generated.ts

@@ -258,6 +258,7 @@ declare type old_as_current_for_Interface_ContainerRuntimeFactoryWithDefaultData
  * typeValidation.broken:
  * "Interface_ContainerRuntimeFactoryWithDefaultDataStoreProps": {"backCompat": false}
  */
+// @ts-expect-error compatibility expected to be broken
 declare type current_as_old_for_Interface_ContainerRuntimeFactoryWithDefaultDataStoreProps = requireAssignableTo<TypeOnly<current.ContainerRuntimeFactoryWithDefaultDataStoreProps>, TypeOnly<old.ContainerRuntimeFactoryWithDefaultDataStoreProps>>
 
 /*

packages/runtime/container-runtime/api-report/container-runtime.legacy.alpha.api.md

@@ -36,7 +36,7 @@ export enum ContainerMessageType {
 export interface ContainerRuntimeOptions {
     readonly chunkSizeInBytes: number;
     readonly compressionOptions: ICompressionRuntimeOptions;
-    readonly createBlobPayloadPending: true | undefined;
+    readonly createBlobPayloadPending: boolean | undefined;
     readonly disableSchemaUpgrade: boolean;
     // @deprecated
     readonly enableGroupedBatching: boolean;

packages/runtime/container-runtime/api-report/container-runtime.legacy.beta.api.md

@@ -36,7 +36,7 @@ export enum ContainerMessageType {
 export interface ContainerRuntimeOptions {
     readonly chunkSizeInBytes: number;
     readonly compressionOptions: ICompressionRuntimeOptions;
-    readonly createBlobPayloadPending: true | undefined;
+    readonly createBlobPayloadPending: boolean | undefined;
     readonly disableSchemaUpgrade: boolean;
     // @deprecated
     readonly enableGroupedBatching: boolean;

packages/runtime/container-runtime/package.json

@@ -233,6 +233,12 @@
 		"broken": {
 			"Interface_LoadContainerRuntimeParams": {
 				"backCompat": false
+			},
+			"Interface_ContainerRuntimeOptions": {
+				"backCompat": false
+			},
+			"TypeAlias_IContainerRuntimeOptions": {
+				"backCompat": false
 			}
 		},
 		"entrypoint": "legacy"

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

@@ -207,6 +207,7 @@ const runtimeOptionsAffectingDocSchemaConfigValidationMap: ConfigValidationMap<R
 		]),
 		createBlobPayloadPending: configValueToMinVersionForCollab([
 			[undefined, "1.0.0"],
+			[false, "1.0.0"],
 			[true, "2.40.0"],
 		]),
 	};

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

@@ -482,10 +482,10 @@ export interface ContainerRuntimeOptions {
 	readonly explicitSchemaControl: boolean;
 
 	/**
-	 * Create blob handles with pending payloads when calling createBlob (default is `undefined` (disabled)).
+	 * Create blob handles with pending payloads when calling createBlob (default is `undefined`/`false` (disabled)).
 	 * When enabled (`true`), createBlob will return a handle before the blob upload completes.
 	 */
-	readonly createBlobPayloadPending: true | undefined;
+	readonly createBlobPayloadPending: boolean | undefined;
 
 	/**
 	 * Controls automatic batch flushing during staging mode.
@@ -1094,7 +1094,10 @@ export class ContainerRuntime
 				(key) =>
 					runtimeOptionKeysThatRequireExplicitSchemaControl.includes(
 						key as RuntimeOptionKeysThatRequireExplicitSchemaControl,
-					) && runtimeOptions[key] !== undefined,
+					) &&
+					runtimeOptions[key] !== undefined &&
+					// `false` is equivalent to the option being disabled/unset, so it doesn't require explicitSchemaControl.
+					runtimeOptions[key] !== false,
 			);
 			if (disallowedKeys.length > 0) {
 				throw new UsageError(`explicitSchemaControl must be enabled to use ${disallowedKeys}`);
@@ -1280,7 +1283,9 @@ export class ContainerRuntime
 				compressionLz4,
 				idCompressorMode,
 				opGroupingEnabled: enableGroupedBatching,
-				createBlobPayloadPending,
+				// Document schema only recognizes `true | undefined` for this feature (see DocumentSchemaValueType),
+				// so normalize an explicit `false` runtime option to `undefined` before persisting.
+				createBlobPayloadPending: createBlobPayloadPending === true ? true : undefined,
 				disallowedVersions: [],
 			},
 			(schema) => {

packages/runtime/container-runtime/src/test/types/validateContainerRuntimePrevious.generated.ts

@@ -105,6 +105,7 @@ declare type old_as_current_for_Interface_ContainerRuntimeOptions = requireAssig
  * typeValidation.broken:
  * "Interface_ContainerRuntimeOptions": {"backCompat": false}
  */
+// @ts-expect-error compatibility expected to be broken
 declare type current_as_old_for_Interface_ContainerRuntimeOptions = requireAssignableTo<TypeOnly<current.ContainerRuntimeOptions>, TypeOnly<old.ContainerRuntimeOptions>>
 
 /*
@@ -772,6 +773,7 @@ declare type old_as_current_for_TypeAlias_IContainerRuntimeOptions = requireAssi
  * typeValidation.broken:
  * "TypeAlias_IContainerRuntimeOptions": {"backCompat": false}
  */
+// @ts-expect-error compatibility expected to be broken
 declare type current_as_old_for_TypeAlias_IContainerRuntimeOptions = requireAssignableTo<TypeOnly<current.IContainerRuntimeOptions>, TypeOnly<old.IContainerRuntimeOptions>>
 
 /*

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

@@ -144,7 +144,7 @@ export function generateRuntimeOptions(
 
 	// Override explicitSchemaControl to enabled if createBlobPayloadPending is enabled
 	pairwiseOptions.map((options) => {
-		if (options.createBlobPayloadPending) {
+		if (options.createBlobPayloadPending === true) {
 			(
 				options as {
 					// Remove readonly modifier to allow overriding