@fluidframework/container-runtime 2.102.0 → 2.103.0

package/src/containerRuntime.ts

@@ -152,7 +152,7 @@ import type {
 	IEventSampler,
 	IFluidErrorBase,
 	ITelemetryGenericEventExt,
-	ITelemetryLoggerExt,
+	TelemetryLoggerExt,
 	MonitoringContext,
 } from "@fluidframework/telemetry-utils/internal";
 import {
@@ -735,7 +735,7 @@ function lastMessageFromMetadata(
  * to understand if/when it is hit.
  * We only want to log this once, to avoid spamming telemetry if we are wrong and these cases are hit commonly.
  */
-export let getSingleUseLegacyLogCallback = (logger: ITelemetryLoggerExt, type: string) => {
+export let getSingleUseLegacyLogCallback = (logger: TelemetryLoggerExt, type: string) => {
 	return (codePath: string): void => {
 		logger.sendTelemetryEvent({
 			eventName: "LegacyMessageFormat",
@@ -1360,7 +1360,25 @@ export class ContainerRuntime
 		return this._getAttachState();
 	}
 
-	public readonly isReadOnly = (): boolean => this.deltaManager.readOnlyInfo.readonly === true;
+	/**
+	 * Whether local op submission is currently disallowed.
+	 *
+	 * This is `true` in two distinct situations.
+	 *
+	 * First: the delta manager reports a read-only connection (host/service-imposed permission or connection state — the historical meaning of `readOnly`).
+	 *
+	 * Second: the `PendingStateManager` is replaying stashed ops (`isApplyingStashedOps`). During this window DDSes must not submit new local ops, as doing so would interleave fresh content ahead of the stashed pending stream and corrupt pending local state. Surfacing it through `isReadOnly()` lets DDSes that consult `readOnly` at realize time self-suppress; see the apply-lifecycle docs on `PendingStateManager` for the full rationale.
+	 *
+	 * Note this layers a third meaning ("transiently quiescing for stashed-op replay") onto the `readOnly` predicate, which is broader than its host/connection-permission origin.
+	 */
+	public readonly isReadOnly = (): boolean =>
+		// `_deltaManager` and `pendingStateManager` are both assigned partway
+		// through the constructor; `baseLogger` is built earlier and stamps
+		// `isReadOnly` on every error event (e.g. layer-compat failures
+		// during construction), so this can be called before either is
+		// assigned. Optional chains keep that window safe.
+		this._deltaManager?.readOnlyInfo.readonly === true ||
+		this.pendingStateManager?.isApplyingStashedOps === true;
 
 	/**
 	 * Current session schema - defines what options are on & off.
@@ -1597,6 +1615,8 @@ export class ContainerRuntime
 
 	private readonly extensions = new Map<ContainerExtensionId, ExtensionEntry>();
 
+	public readonly baseLogger: ITelemetryBaseLogger;
+
 	/***/
 	protected constructor(
 		context: IContainerContext,
@@ -1610,7 +1630,7 @@ export class ContainerRuntime
 		private readonly runtimeOptions: Readonly<ContainerRuntimeOptionsInternal>,
 		private readonly containerScope: FluidObject,
 		// Create a custom ITelemetryBaseLogger to output telemetry events.
-		public readonly baseLogger: ITelemetryBaseLogger,
+		baseLogger: ITelemetryBaseLogger,
 		existing: boolean,
 
 		blobManagerLoadInfo: IBlobManagerLoadInfo,
@@ -1663,15 +1683,20 @@ export class ContainerRuntime
 
 		this.isSnapshotInstanceOfISnapshot = snapshotWithContents !== undefined;
 
-		this.mc = createChildMonitoringContext({
-			logger: this.baseLogger,
-			namespace: "ContainerRuntime",
+		this.baseLogger = createChildLogger({
+			logger: baseLogger,
 			properties: {
-				all: {
-					inStagingMode: this.inStagingMode,
+				error: {
+					inStagingMode: () => this.inStagingMode,
+					isApplyingStashedOps: () => this.pendingStateManager?.isApplyingStashedOps,
+					isReadOnly: () => this.isReadOnly(),
 				},
 			},
 		});
+		this.mc = createChildMonitoringContext({
+			logger: this.baseLogger,
+			namespace: "ContainerRuntime",
+		});
 
 		// Validate that the Loader is compatible with this Runtime.
 		const maybeLoaderCompatDetailsForRuntime = context as FluidObject<ILayerCompatDetails>;
@@ -1840,6 +1865,18 @@ export class ContainerRuntime
 			},
 			pendingRuntimeState?.pending,
 			this.baseLogger,
+			{
+				// PSM has cleared `isApplyingStashedOps`; `isReadOnly()` now
+				// reflects the network-readonly state again. Fan out so DDSes
+				// know they can submit once more. No open hook is needed —
+				// the apply window opens before `channelCollection` exists,
+				// so a fanout there would be a no-op; data stores instead
+				// pick up the initial readonly state from `isReadOnly()`
+				// when they're first asked.
+				onAfterStashedOpsApplied: () => {
+					this.notifyReadOnlyState();
+				},
+			},
 		);
 
 		let outerDeltaManager: IDeltaManagerFull = this.innerDeltaManager;
@@ -2187,6 +2224,14 @@ export class ContainerRuntime
 			telemetryDocumentId: this.telemetryDocumentId,
 			groupedBatchingEnabled: this.groupedBatchingEnabled,
 			initialSequenceNumber: this.deltaManager.initialSequenceNumber,
+			// Number of ops since the last summary that this client is aware of (including ops still
+			// queued for processing). Computed as the gap between the latest known op sequence number
+			// and the sequence number of the message at which the last summary was taken (per snapshot
+			// metadata). Falls back to lastKnownSeqNumber when no prior summary message is recorded
+			// (e.g. new container or older snapshot without metadata).
+			numUnsummarizedOps:
+				this.deltaManager.lastKnownSeqNumber -
+				(this.messageAtLastSummary?.sequenceNumber ?? 0),
 			minVersionForCollab: this.minVersionForCollab,
 			// logging hardware telemetry
 			deviceSpec: { ...getDeviceSpec() },
@@ -2805,6 +2850,28 @@ export class ContainerRuntime
 			return;
 		}
 
+		// Invariant: the canSendOps edge in `setConnectionStateCore` — the
+		// only caller of this method — cannot fire while
+		// `applyStashedOpsAt` is in flight, because the loader awaits the
+		// apply before transitioning the runtime to a write-capable
+		// connection. If this assert ever fires, that contract has changed
+		// and the submit guard at `submit()` would catch a runtime-internal
+		// resubmit (`Rejoin`, `GC`, `FluidDataStoreOp`) for an op type
+		// outside the apply-window allowlist.
+		//
+		// The precondition is held by the load sequence: `loadRuntime2`
+		// awaits `pendingStateManager.applyStashedOpsAt(...)` before
+		// returning the runtime, and the loader gates `setLoaded` on that
+		// completion before any write-capable connection edge fires. A
+		// maintainer reordering either sequence (or adding a new
+		// `canSendOps` edge that fires before the apply resolves) is what
+		// would trip this assert.
+		// @see {@link ContainerRuntime.loadRuntime2} (awaits `applyStashedOpsAt`)
+		assert(
+			!this.pendingStateManager.isApplyingStashedOps,
+			0xd01 /* replayPendingStates must not be called during stashed-op apply window */,
+		);
+
 		// Replaying is an internal operation and we don't want to generate noise while doing it.
 		// So temporarily disable dirty state change events, and save the old state.
 		// When we're done, we'll emit the event if the state changed.
@@ -2920,8 +2987,14 @@ export class ContainerRuntime
 		}
 	}
 
-	private readonly notifyReadOnlyState = (readonly: boolean): void =>
-		this.channelCollection.notifyReadOnlyState(readonly);
+	// Boolean payload from the `"readonly"` delta-manager event is intentionally
+	// ignored — `isReadOnly()` aggregates delta-manager readonly with the PSM
+	// apply window, and that aggregation is the source of truth for fanout.
+	// `channelCollection?.` guards against future wiring changes; both callers
+	// today (the `"readonly"` listener and `onAfterStashedOpsApplied`) fire
+	// after `channelCollection` is assigned.
+	private readonly notifyReadOnlyState = (_readonly?: boolean): void =>
+		this.channelCollection?.notifyReadOnlyState(this.isReadOnly());
 
 	public setConnectionState(canSendOps: boolean, clientId?: string): void {
 		this.setConnectionStateToConnectedOrDisconnected(canSendOps, clientId);
@@ -4078,7 +4151,7 @@ export class ContainerRuntime
 		/**
 		 * Logger to use for correlated summary events
 		 */
-		summaryLogger?: ITelemetryLoggerExt;
+		summaryLogger?: TelemetryLoggerExt;
 		/**
 		 * True to run garbage collection before summarizing; defaults to true
 		 */
@@ -4287,7 +4360,7 @@ export class ContainerRuntime
 			/**
 			 * Logger to use for logging GC events
 			 */
-			logger?: ITelemetryLoggerExt;
+			logger?: TelemetryLoggerExt;
 			/**
 			 * True to run GC sweep phase after the mark phase
 			 */
@@ -4718,7 +4791,7 @@ export class ContainerRuntime
 	 * @returns failed summarize result (IBaseSummarizeResult) if summary should be failed, undefined otherwise.
 	 */
 	private async shouldFailSummaryOnPendingOps(
-		logger: ITelemetryLoggerExt,
+		logger: TelemetryLoggerExt,
 		referenceSequenceNumber: number,
 		minimumSequenceNumber: number,
 		finalAttempt: boolean,
@@ -4840,6 +4913,52 @@ export class ContainerRuntime
 	): void {
 		this.verifyNotClosed();
 
+		// Nothing should be submitting while we're replaying stashed ops.
+		// The runtime is readonly during the apply window (see
+		// `PendingStateManager._applyLifecycle`), so a compliant DDS skips
+		// submits. If we land here anyway, a DDS bypassed the readonly gate
+		// (e.g. a realize-time write that doesn't consult `readOnly`) and
+		// produced a local op that has no counterpart in the saved-op
+		// replay — we cannot reconcile the mismatch, so fail fatally. We
+		// check here (rather than at flush) because outbox flushes are
+		// deferred and the apply window could close before the offending op
+		// reaches the pending queue.
+		//
+		// Allowlist: `BlobAttach` is a runtime-internal op type that may
+		// legitimately fire during apply — produced by `sharePendingBlobs`,
+		// which is invoked from `loadRuntime2` before `applyStashedOpsAt`
+		// resolves. `IdAllocation` is not in this allowlist because the
+		// assert at 0x9a5 below enforces that it never reaches `submit()`
+		// at all; treating that assert as the single source of truth.
+		//
+		// Always surface the error event to telemetry on a bypass so we can
+		// attribute incidents regardless of the on-switch state. The
+		// `EnableSubmitDuringStashedApplyThrow` config opts in to the
+		// throw + container close; by default we log only, so a first- or
+		// third-party DDS that quietly bypasses the readonly gate in
+		// production is observable without escalating to a fatal close.
+		if (
+			this.pendingStateManager.isApplyingStashedOps &&
+			containerRuntimeMessage.type !== ContainerMessageType.BlobAttach
+		) {
+			const error = new UsageError("Local op submitted during stashed-op apply window", {
+				messageType: containerRuntimeMessage.type,
+			});
+			this.mc.logger.sendErrorEvent({ eventName: "SubmitDuringStashedOpApply" }, error);
+			if (
+				this.mc.config.getBoolean(
+					"Fluid.ContainerRuntime.EnableSubmitDuringStashedApplyThrow",
+				) === true
+			) {
+				// Close the container before throwing so the "throw + close"
+				// contract is enforced by this code path rather than by
+				// whichever caller happens to wrap the throw in `.catch(closeFn)`.
+				// `closeFn` is idempotent; a caller that also closes won't double-close.
+				this.closeFn(error);
+				throw error;
+			}
+		}
+
 		// There should be no ops in detached container state!
 		assert(
 			this.attachState !== AttachState.Detached,
@@ -5228,7 +5347,7 @@ export class ContainerRuntime
 	private async fetchLatestSnapshotAndMaybeClose(
 		targetRefSeq: number,
 		targetAckHandle: string,
-		logger: ITelemetryLoggerExt,
+		logger: TelemetryLoggerExt,
 	): Promise<void> {
 		const fetchedSnapshotRefSeq = await PerformanceEvent.timedExecAsync(
 			logger,

package/src/dataStore.ts

@@ -13,7 +13,7 @@ import type {
 	IFluidDataStoreChannel,
 } from "@fluidframework/runtime-definitions/internal";
 import {
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 	TelemetryDataTag,
 	UsageError,
 } from "@fluidframework/telemetry-utils/internal";
@@ -58,7 +58,7 @@ export const channelToDataStore = (
 	fluidDataStoreChannel: IFluidDataStoreChannel,
 	internalId: string,
 	channelCollection: ChannelCollection,
-	logger: ITelemetryLoggerExt,
+	logger: TelemetryLoggerExt,
 ): IDataStore => new DataStore(fluidDataStoreChannel, internalId, channelCollection, logger);
 
 enum AliasState {
@@ -194,7 +194,7 @@ class DataStore implements IDataStore {
 		private readonly fluidDataStoreChannel: IFluidDataStoreChannel,
 		private readonly internalId: string,
 		private readonly channelCollection: ChannelCollection,
-		private readonly logger: ITelemetryLoggerExt,
+		private readonly logger: TelemetryLoggerExt,
 		private readonly parentContext = channelCollection.parentContext,
 	) {
 		this.pendingAliases = channelCollection.pendingAliases;

package/src/dataStoreContexts.ts

@@ -6,7 +6,7 @@
 import type { IDisposable, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert, Deferred, Lazy } from "@fluidframework/core-utils/internal";
 import {
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 	createChildLogger,
 } from "@fluidframework/telemetry-utils/internal";
 
@@ -68,7 +68,7 @@ export class DataStoreContexts
 		}
 	});
 
-	private readonly _logger: ITelemetryLoggerExt;
+	private readonly _logger: TelemetryLoggerExt;
 
 	constructor(baseLogger: ITelemetryBaseLogger) {
 		this._logger = createChildLogger({ logger: baseLogger });

package/src/deltaScheduler.ts

@@ -7,10 +7,7 @@ import { performanceNow, type TypedEventEmitter } from "@fluid-internal/client-u
 import type { IDeltaManagerFull } from "@fluidframework/container-definitions/internal";
 import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 import type { IContainerRuntimeBaseEvents } from "@fluidframework/runtime-definitions/internal";
-import {
-	type ITelemetryLoggerExt,
-	formatTick,
-} from "@fluidframework/telemetry-utils/internal";
+import { type TelemetryLoggerExt, formatTick } from "@fluidframework/telemetry-utils/internal";
 
 /**
  * DeltaScheduler is responsible for the scheduling of inbound delta queue in cases where there
@@ -55,7 +52,7 @@ export class DeltaScheduler {
 	constructor(
 		private readonly deltaManager: IDeltaManagerFull,
 		private readonly runtimeEventsEmitter: TypedEventEmitter<IContainerRuntimeBaseEvents>,
-		private readonly logger: ITelemetryLoggerExt,
+		private readonly logger: TelemetryLoggerExt,
 	) {
 		this.deltaManager.inbound.on("idle", this.inboundQueueIdle);
 		runtimeEventsEmitter.on("batchBegin", this.batchBegin);

package/src/gc/garbageCollection.ts

@@ -19,7 +19,7 @@ import {
 	responseToException,
 } from "@fluidframework/runtime-utils/internal";
 import {
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 	DataProcessingError,
 	type MonitoringContext,
 	PerformanceEvent,
@@ -498,7 +498,7 @@ export class GarbageCollector implements IGarbageCollector {
 			/**
 			 * Logger to use for logging GC events
 			 */
-			logger?: ITelemetryLoggerExt;
+			logger?: TelemetryLoggerExt;
 			/**
 			 * True to run GC sweep phase after the mark phase
 			 */
@@ -605,7 +605,7 @@ export class GarbageCollector implements IGarbageCollector {
 	private async runGC(
 		fullGC: boolean,
 		currentReferenceTimestampMs: number,
-		logger: ITelemetryLoggerExt,
+		logger: TelemetryLoggerExt,
 	): Promise<IGCStats> {
 		// 1. Generate / analyze the runtime's reference graph.
 		// Get the reference graph (gcData) and run GC algorithm to get referenced / unreferenced nodes.
@@ -796,7 +796,7 @@ export class GarbageCollector implements IGarbageCollector {
 	private findAllNodesReferencedBetweenGCs(
 		currentGCData: IGarbageCollectionData,
 		previousGCData: IGarbageCollectionData | undefined,
-		logger: ITelemetryLoggerExt,
+		logger: TelemetryLoggerExt,
 	): string[] | undefined {
 		// If we haven't run GC before there is nothing to do.
 		// No previousGCData, means nothing is unreferenced, and there are no reference state trackers to clear

package/src/gc/gcDefinitions.ts

@@ -14,7 +14,7 @@ import type {
 } from "@fluidframework/runtime-definitions/internal";
 import type { ReadAndParseBlob } from "@fluidframework/runtime-utils/internal";
 import type {
-	ITelemetryLoggerExt,
+	TelemetryLoggerExt,
 	ITelemetryPropertiesExt,
 } from "@fluidframework/telemetry-utils/internal";
 
@@ -396,7 +396,7 @@ export interface IGarbageCollector {
 	 */
 	collectGarbage(
 		options: {
-			logger?: ITelemetryLoggerExt;
+			logger?: TelemetryLoggerExt;
 			runSweep?: boolean;
 			fullGC?: boolean;
 		},
@@ -505,7 +505,7 @@ export interface IGarbageCollectorCreateParams {
 	readonly closeFn: (error: ICriticalContainerError) => void;
 
 	readonly gcOptions: IGCRuntimeOptions;
-	readonly baseLogger: ITelemetryLoggerExt;
+	readonly baseLogger: TelemetryLoggerExt;
 	readonly existing: boolean;
 
 	readonly metadata: IContainerRuntimeMetadata | undefined;

package/src/gc/gcTelemetry.ts

@@ -6,7 +6,7 @@
 import type { Tagged } from "@fluidframework/core-interfaces";
 import type { IGarbageCollectionData } from "@fluidframework/runtime-definitions/internal";
 import {
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 	type MonitoringContext,
 	generateStack,
 	tagCodeArtifacts,
@@ -350,7 +350,7 @@ export class GCTelemetryTracker {
 		currentGCData: IGarbageCollectionData,
 		previousGCData: IGarbageCollectionData,
 		explicitReferences: Map<string, string[]>,
-		logger: ITelemetryLoggerExt,
+		logger: TelemetryLoggerExt,
 	): void {
 		for (const [nodeId, currentOutboundRoutes] of Object.entries(currentGCData.gcNodes)) {
 			const previousRoutes = previousGCData.gcNodes[nodeId] ?? [];
@@ -395,7 +395,7 @@ export class GCTelemetryTracker {
 	 * Log events that are pending in pendingEventsQueue. This is called after GC runs in the summarizer client
 	 * so that the state of an unreferenced node is updated.
 	 */
-	public async logPendingEvents(logger: ITelemetryLoggerExt): Promise<void> {
+	public async logPendingEvents(logger: TelemetryLoggerExt): Promise<void> {
 		// Events sent come only from the summarizer client. In between summaries, events are pushed to a queue and at
 		// summary time they are then logged.
 		// Events generated:

package/src/inboundBatchAggregator.ts

@@ -9,7 +9,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 import { isRuntimeMessage } from "@fluidframework/driver-utils/internal";
 import {
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 	DataCorruptionError,
 	DataProcessingError,
 	extractSafePropertiesFromMessage,
@@ -38,7 +38,7 @@ export class InboundBatchAggregator {
 	constructor(
 		private readonly deltaManager: IDeltaManagerFull,
 		private readonly getClientId: () => string | undefined,
-		private readonly logger: ITelemetryLoggerExt,
+		private readonly logger: TelemetryLoggerExt,
 	) {
 		// Listen for updates and peek at the inbound
 		this.deltaManager.inbound.on("push", this.trackPending);

package/src/opLifecycle/opCompressor.ts

@@ -9,7 +9,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import {
 	DataProcessingError,
 	createChildLogger,
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 import { compress } from "lz4js";
 
@@ -25,7 +25,7 @@ import { estimateSocketSize } from "./outbox.js";
  * Use opGroupingManager to group a batch into a singleton batch suitable for compression.
  */
 export class OpCompressor {
-	private readonly logger: ITelemetryLoggerExt;
+	private readonly logger: TelemetryLoggerExt;
 
 	constructor(logger: ITelemetryBaseLogger) {
 		this.logger = createChildLogger({ logger, namespace: "OpCompressor" });

package/src/opLifecycle/opDecompressor.ts

@@ -9,7 +9,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 import {
 	createChildLogger,
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 import { decompress } from "lz4js";
 
@@ -40,7 +40,7 @@ export class OpDecompressor {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	private rootMessageContents: any | undefined;
 	private processedCount = 0;
-	private readonly logger: ITelemetryLoggerExt;
+	private readonly logger: TelemetryLoggerExt;
 
 	constructor(logger: ITelemetryBaseLogger) {
 		this.logger = createChildLogger({ logger, namespace: "OpDecompressor" });

package/src/opLifecycle/opGroupingManager.ts

@@ -8,7 +8,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 import {
 	createChildLogger,
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 
 import type {
@@ -65,7 +65,7 @@ export interface EmptyGroupedBatch {
 
 export class OpGroupingManager {
 	static readonly groupedBatchOp = "groupedBatch";
-	private readonly logger: ITelemetryLoggerExt;
+	private readonly logger: TelemetryLoggerExt;
 
 	constructor(
 		private readonly config: OpGroupingManagerConfig,

package/src/opLifecycle/opSplitter.ts

@@ -11,7 +11,7 @@ import {
 	DataCorruptionError,
 	createChildLogger,
 	extractSafePropertiesFromMessage,
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -45,7 +45,7 @@ function isChunkedContents(contents: unknown): contents is IChunkedContents {
 export class OpSplitter {
 	// Local copy of incomplete received chunks.
 	private readonly chunkMap: Map<string, string[]>;
-	private readonly logger: ITelemetryLoggerExt;
+	private readonly logger: TelemetryLoggerExt;
 
 	constructor(
 		chunks: [string, string[]][],

package/src/opLifecycle/outbox.ts

@@ -14,7 +14,7 @@ import {
 	UsageError,
 	createChildLogger,
 	type IFluidErrorBase,
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 
 import type { ICompressionRuntimeOptions } from "../compressionDefinitions.js";
@@ -194,7 +194,7 @@ export const estimateSocketSize = (batch: OutboundBatch): number => {
  * to support slight variation in semantics for each batch (e.g. support for rebasing or grouping).
  */
 export class Outbox {
-	private readonly logger: ITelemetryLoggerExt;
+	private readonly logger: TelemetryLoggerExt;
 	private readonly mainBatch: BatchManager;
 	private readonly blobAttachBatch: BatchManager;
 	private batchRebasesToReport = 5;

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-runtime";
-export const pkgVersion = "2.102.0";
+export const pkgVersion = "2.103.0";

package/src/pendingStateManager.ts

@@ -6,7 +6,7 @@
 import type { IDisposable, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert, Lazy } from "@fluidframework/core-utils/internal";
 import {
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 	DataProcessingError,
 	LoggingError,
 	extractSafePropertiesFromMessage,
@@ -142,6 +142,25 @@ export interface IRuntimeStateHandler {
 	isAttached: () => boolean;
 }
 
+/**
+ * Optional hooks invoked at the close of the stashed-op apply lifecycle.
+ *
+ * `onAfterStashedOpsApplied` fires synchronously the first time
+ * `initialMessages` drains during `applyStashedOpsAt`, immediately after
+ * `isApplyingStashedOps` flips to `false`. Fires at most once per PSM
+ * lifetime. If an apply throws, control never reaches the close site and
+ * the hook is not invoked — load is fatal in that case.
+ *
+ * No corresponding open hook is exposed. The apply window is opened eagerly
+ * in the PSM constructor, but at that point `ContainerRuntime` has not yet
+ * wired up the downstream observers (`channelCollection` is undefined), so a
+ * fanout fired from the constructor would be a no-op. Consumers that care
+ * about the open transition can read `isApplyingStashedOps` directly.
+ */
+export interface PendingStateManagerHooks {
+	onAfterStashedOpsApplied?: () => void;
+}
+
 function isEmptyBatchPendingMessage(message: IPendingMessageFromStash): boolean {
 	const content = JSON.parse(message.content) as Partial<EmptyGroupedBatch>;
 	return content.type === "groupedBatch" && content.contents?.length === 0;
@@ -366,17 +385,62 @@ export class PendingStateManager implements IDisposable {
 		};
 	}
 
-	private readonly logger: ITelemetryLoggerExt;
+	private readonly logger: TelemetryLoggerExt;
+
+	/**
+	 * One-way lifecycle of the stashed-op apply window: `ended` → `applying` → `ended`.
+	 *
+	 * Default is `ended` — no stashed state means there's nothing to apply, so the window is
+	 * closed before it ever opens. `ended` → `applying` happens in the constructor when
+	 * stashed state is present (i.e. `initialMessages` is non-empty at construction). The
+	 * open is eager so the runtime is readonly from the moment any DDS could possibly
+	 * observe it. `applying` → `ended` happens the first time {@link applyStashedOpsAt}
+	 * drains `initialMessages`. After that, local edits are safe — they queue FIFO behind
+	 * any remaining `pendingMessages`, preserving server-side ordering.
+	 *
+	 * The window never reopens. After the close, subsequent `applyStashedOpsAt` calls (e.g.
+	 * from late `notifyOpReplay`s) early-return at the empty guard.
+	 *
+	 * `pendingMessages` state is intentionally NOT part of the close condition. Those
+	 * entries are drained transparently by {@link replayPendingStates} on connect via
+	 * resubmit (each pop is matched by a fresh push), so the queue size is conserved across
+	 * resubmit and DDSes can't distinguish a resubmit-ack from a normal ack. Holding the
+	 * window open through resubmit would force resubmits to run while the runtime is
+	 * readonly, which is the inverse of what we want ("never resubmit during apply stashed
+	 * ops").
+	 *
+	 * An apply error leaves the lifecycle at `applying` because the queue isn't drained.
+	 * That's fine: an error here is fatal for the load, the container is unusable, and
+	 * there's no state to restore.
+	 */
+	private _applyLifecycle: "applying" | "ended" = "ended";
+	public get isApplyingStashedOps(): boolean {
+		return this._applyLifecycle === "applying";
+	}
+
+	private readonly hooks: PendingStateManagerHooks;
 
 	constructor(
 		private readonly stateHandler: IRuntimeStateHandler,
 		stashedLocalState: IPendingLocalState | undefined,
 		logger: ITelemetryBaseLogger,
+		hooks: PendingStateManagerHooks = {},
 	) {
 		this.logger = createChildLogger({ logger });
+		this.hooks = hooks;
 		if (stashedLocalState?.pendingStates) {
 			this.initialMessages.push(...stashedLocalState.pendingStates);
 		}
+		// Open the apply window eagerly if there is any stashed work. The
+		// runtime is readonly while `isApplyingStashedOps` is true (see
+		// `ContainerRuntime.isReadOnly`); compliant DDSes consult `readOnly`
+		// at realize time and skip submits. No fanout fires here — downstream
+		// observers (`channelCollection`) are not yet constructed at this
+		// point in the runtime constructor, and the first real readonly read
+		// happens after the constructor returns.
+		if (!this.initialMessages.isEmpty()) {
+			this._applyLifecycle = "applying";
+		}
 	}
 
 	public get disposed(): boolean {
@@ -451,6 +515,10 @@ export class PendingStateManager implements IDisposable {
 	 * @param seqNum - Sequence number at which to apply ops. Will apply all ops if seqNum is undefined.
 	 */
 	public async applyStashedOpsAt(seqNum?: number): Promise<void> {
+		if (this.initialMessages.isEmpty()) {
+			return;
+		}
+
 		// apply stashed ops at sequence number
 		while (!this.initialMessages.isEmpty()) {
 			if (seqNum !== undefined) {
@@ -497,6 +565,16 @@ export class PendingStateManager implements IDisposable {
 				throw DataProcessingError.wrapIfUnrecognized(error, "applyStashedOp", nextMessage);
 			}
 		}
+
+		// The apply window was opened eagerly in the constructor when there
+		// was any stashed work. We close it on full successful drain only.
+		// If an apply throws above, control never reaches here and the
+		// lifecycle stays at "applying" — the load is fatal so there's no
+		// recoverable state.
+		if (this._applyLifecycle === "applying" && this.initialMessages.isEmpty()) {
+			this._applyLifecycle = "ended";
+			this.hooks.onAfterStashedOpsApplied?.();
+		}
 	}
 
 	/**