feat(container-loader): add readOnly option to loadFrozenContainerFromPendingState

.changeset/frozen-container-readonly-option.md

@@ -0,0 +1,11 @@
+---
+"@fluidframework/container-loader": minor
+"__section": feature
+---
+Add readOnly option to loadFrozenContainerFromPendingState
+
+`loadFrozenContainerFromPendingState` and `createFrozenDocumentServiceFactory` now accept an optional `readOnly` parameter (default `true`, preserving existing behavior).
+
+When `readOnly: false`, the frozen container loads as writable so the runtime accepts DDS submissions. The first runtime submit triggers an internal read→write upgrade attempt that cannot succeed (no upstream, no quorum join op), so the container settles into `Disconnected`. DDS local apply continues, and submitted ops accumulate in the runtime's pending-state manager — this is the state needed to accrue and capture additional pending state without publishing it.
+
+Use `readOnly: false` when the caller wants to load a frozen container, apply additional local changes, and capture the resulting pending state via `getPendingLocalState()`.

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

@@ -24,7 +24,7 @@ export interface ContainerAlpha extends IContainer {
 export function createDetachedContainer(createDetachedContainerProps: ICreateDetachedContainerProps): Promise<IContainer>;
 
 // @alpha @legacy
-export function createFrozenDocumentServiceFactory(factory?: IDocumentServiceFactory | Promise<IDocumentServiceFactory>): IDocumentServiceFactory;
+export function createFrozenDocumentServiceFactory(factory?: IDocumentServiceFactory | Promise<IDocumentServiceFactory>, readOnly?: boolean): IDocumentServiceFactory;
 
 // @beta @legacy (undocumented)
 export interface IBaseProtocolHandler {
@@ -106,6 +106,7 @@ export interface ILoadExistingContainerProps extends ICreateAndLoadContainerProp
 // @alpha @legacy
 export interface ILoadFrozenContainerFromPendingStateProps extends ILoadExistingContainerProps {
     readonly pendingLocalState: string;
+    readonly readOnly?: boolean;
 }
 
 // @alpha @legacy

packages/loader/container-loader/src/connectionManager.ts

@@ -582,9 +582,9 @@ export class ConnectionManager implements IConnectionManager {
 					LogLevel.verbose,
 				);
 				if (isDeltaStreamConnectionForbiddenError(origError)) {
-					connection = new FrozenDeltaStream(origError.storageOnlyReason, {
-						text: origError.message,
-						error: origError,
+					connection = new FrozenDeltaStream({
+						storageOnlyReason: origError.storageOnlyReason,
+						readonlyConnectionReason: { text: origError.message, error: origError },
 					});
 					requestedMode = "read";
 					break;
@@ -594,9 +594,8 @@ export class ConnectionManager implements IConnectionManager {
 				) {
 					// If we get out of storage error from calling joinsession, then use the NoDeltaStream object so
 					// that user can at least load the container.
-					connection = new FrozenDeltaStream(undefined, {
-						text: origError.message,
-						error: origError,
+					connection = new FrozenDeltaStream({
+						readonlyConnectionReason: { text: origError.message, error: origError },
 					});
 					requestedMode = "read";
 					break;
@@ -1095,6 +1094,15 @@ export class ConnectionManager implements IConnectionManager {
 		// Note that we also want nacks to be rare and be treated as catastrophic failures.
 		// Be careful with reentrancy though - disconnected event should not be be raised in the
 		// middle of the current workflow, but rather on clean stack!
+		//
+		// Tripwire: writable-frozen container loads (`loadFrozenContainerFromPendingState({
+		// readOnly: false })`) depend on this short-circuit. Their FrozenDeltaStream is mode
+		// "read", so a runtime submit lands here, the deferred `reconnect("write")` reaches
+		// FrozenDocumentService.connectToDeltaStream({ mode: "write" }) which hangs the
+		// promise, and the runtime's outbox skips actual send so ops accumulate in
+		// pendingStateManager. If this short-circuit is refactored to call submit directly
+		// instead of triggering a reconnect, writable-frozen loses its only mechanism for
+		// capturing additional pending state — see frozenServices.ts JSDoc.
 		if (this.connectionMode === "read") {
 			if (!this.pendingReconnect) {
 				this.pendingReconnect = true;

packages/loader/container-loader/src/createAndLoadContainerUtils.ts

@@ -229,6 +229,28 @@ export interface ILoadFrozenContainerFromPendingStateProps
 	 * Pending local state to be applied to the container.
 	 */
 	readonly pendingLocalState: string;
+
+	/**
+	 * Controls whether the frozen container is surfaced as read-only.
+	 *
+	 * Defaults to `true`. When `true`, the container reports `readOnlyInfo.readonly === true`
+	 * with `storageOnly === true`, matching the historical behavior of frozen loads.
+	 *
+	 * When `false`, the container loads as writable so the runtime will accept DDS submissions.
+	 * The first submission triggers an internal read→write upgrade attempt that cannot succeed
+	 * (no upstream, no quorum join op), so the container settles into a `Disconnected` state.
+	 * Local DDS state continues to update via optimistic apply, and submitted ops accumulate in
+	 * the runtime's pending-state manager. Use this when callers want to accrue and capture
+	 * pending state without publishing it.
+	 *
+	 * @remarks
+	 * The flag uses negative polarity (`readOnly`) rather than a positive opt-in (`writable`)
+	 * to align with `IContainer.readOnlyInfo.readonly`, which is the established surface for
+	 * read/write state on a loaded container. A future positive-polarity option can layer on
+	 * top of this without breaking callers, but flipping the polarity now would split readers
+	 * between two conventions for the same concept.
+	 */
+	readonly readOnly?: boolean;
 }
 
 /**
@@ -241,7 +263,10 @@ export async function loadFrozenContainerFromPendingState(
 ): Promise<IContainer> {
 	return loadExistingContainer({
 		...props,
-		documentServiceFactory: createFrozenDocumentServiceFactory(props.documentServiceFactory),
+		documentServiceFactory: createFrozenDocumentServiceFactory(
+			props.documentServiceFactory,
+			props.readOnly,
+		),
 	});
 }