@fluidframework/container-runtime 2.0.0-dev-rc.5.0.0.265721 → 2.0.0-dev-rc.5.0.0.268409

package/src/gc/gcSummaryStateTracker.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { SummaryType } from "@fluidframework/protocol-definitions";
+import { SummaryType } from "@fluidframework/driver-definitions";
 import {
 	ISummaryTreeWithStats,
 	ISummarizeResult,
@@ -16,7 +16,7 @@ import { SummaryTreeBuilder, mergeStats } from "@fluidframework/runtime-utils/in
 
 import { IRefreshSummaryResult } from "../summary/index.js";
 
-import { GCVersion, IGCStats, IGarbageCollectorConfigs } from "./gcDefinitions.js";
+import { IGCStats, IGarbageCollectorConfigs } from "./gcDefinitions.js";
 import { generateSortedGCState } from "./gcHelpers.js";
 import { IGarbageCollectionSnapshotData, IGarbageCollectionState } from "./gcSummaryDefinitions.js";
 
@@ -38,17 +38,11 @@ export interface IGCSummaryTrackingData {
  * On summarize, it decides whether to write new state or re-use previous summary's state.
  */
 export class GCSummaryStateTracker {
-	// This is the version of GC data in the latest summary being tracked.
-	private latestSummaryGCVersion: GCVersion;
-
 	// Keeps track of the GC data from the latest summary successfully acked by the server.
 	private latestSummaryData: IGCSummaryTrackingData | undefined;
 	// Keeps track of the GC data from the last summary submitted to the server but not yet acked.
 	private pendingSummaryData: IGCSummaryTrackingData | undefined;
 
-	// Tracks whether there was GC was run in latest summary being tracked.
-	private wasGCRunInLatestSummary: boolean;
-
 	// Tracks the count of data stores whose state updated since the last summary, i.e., they went from referenced
 	// to unreferenced or vice-versa.
 	public updatedDSCountSinceLastSummary: number = 0;
@@ -69,58 +63,9 @@ export class GCSummaryStateTracker {
 		// Tells whether GC should run or not.
 		private readonly configs: Pick<
 			IGarbageCollectorConfigs,
-			"shouldRunGC" | "tombstoneMode" | "gcVersionInBaseSnapshot" | "gcVersionInEffect"
+			"gcEnabled" | "tombstoneMode" | "gcVersionInBaseSnapshot" | "gcVersionInEffect"
 		>,
-		// Tells whether GC was run in the base snapshot this container loaded from.
-		wasGCRunInBaseSnapshot: boolean,
-	) {
-		this.wasGCRunInLatestSummary = wasGCRunInBaseSnapshot;
-		// For existing document, the latest summary is the one that we loaded from. So, use its GC version as the
-		// latest tracked GC version. For new documents, we will be writing the first summary with the current version.
-		this.latestSummaryGCVersion =
-			this.configs.gcVersionInBaseSnapshot ?? this.configs.gcVersionInEffect;
-	}
-
-	/**
-	 * Tells whether the GC state needs to be reset. This can happen under 3 conditions:
-	 *
-	 * 1. The base snapshot contains GC state but GC is disabled. This will happen the first time GC is disabled after
-	 * it was enabled before. GC state needs to be removed from summary and all nodes should be marked referenced.
-	 *
-	 * 2. The base snapshot does not have GC state but GC is enabled. This will happen the very first time GC runs on
-	 * a document and the first time GC is enabled after is was disabled before.
-	 *
-	 * 3. GC is enabled and the latest summary state is refreshed from a snapshot that had GC disabled and vice-versa.
-	 *
-	 * Note that the state will be reset only once for the first summary generated after this returns true. After that,
-	 * this will return false.
-	 */
-	public get doesGCStateNeedReset(): boolean {
-		return this.wasGCRunInLatestSummary !== this.configs.shouldRunGC;
-	}
-
-	/**
-	 * Tells whether the GC state needs to be reset in the next summary. We need to do this if:
-	 *
-	 * 1. GC was enabled and is now disabled. The GC state needs to be removed and everything becomes referenced.
-	 *
-	 * 2. GC was disabled and is now enabled. The GC state needs to be regenerated and added to summary.
-	 *
-	 * 3. GC is enabled and the latest summary state is refreshed from a snapshot that had GC disabled and vice-versa.
-	 *
-	 * 4. The GC version in the latest summary is different from the current GC version. This can happen if:
-	 *
-	 * 4.1. The summary this client loaded with has data from a different GC version.
-	 *
-	 * 4.2. This client's latest summary was updated from a snapshot that has a different GC version.
-	 */
-	public get doesSummaryStateNeedReset(): boolean {
-		return (
-			this.doesGCStateNeedReset ||
-			(this.configs.shouldRunGC &&
-				this.latestSummaryGCVersion !== this.configs.gcVersionInEffect)
-		);
-	}
+	) {}
 
 	/**
 	 * Called during GC initialization. Initialize the latest summary data from the base snapshot data.
@@ -152,7 +97,7 @@ export class GCSummaryStateTracker {
 		deletedNodes: Set<string>,
 		tombstones: string[],
 	): ISummarizeResult | undefined {
-		if (!this.configs.shouldRunGC) {
+		if (!this.configs.gcEnabled) {
 			return;
 		}
 
@@ -283,25 +228,14 @@ export class GCSummaryStateTracker {
 	 * Called to refresh the latest summary state. This happens when a pending summary is acked.
 	 */
 	public async refreshLatestSummary(result: IRefreshSummaryResult): Promise<void> {
-		if (!result.isSummaryTracked) {
-			return;
-		}
-
-		// If the summary is tracked, this client is the one that generated it. So, update wasGCRunInLatestSummary.
-		// Note that this has to be updated if GC did not run too. Otherwise, `gcStateNeedsReset` will always return
-		// true in scenarios where GC is currently disabled but enabled in the snapshot we loaded from.
-		this.wasGCRunInLatestSummary = this.configs.shouldRunGC;
-
-		if (!this.configs.shouldRunGC) {
+		if (!this.configs.gcEnabled || !result.isSummaryTracked) {
 			return;
 		}
 
-		this.latestSummaryGCVersion = this.configs.gcVersionInEffect;
 		this.latestSummaryData = this.pendingSummaryData;
 		this.pendingSummaryData = undefined;
 		this.updatedDSCountSinceLastSummary = 0;
 		this.fullGCModeForAutoRecovery = false;
-		return;
 	}
 
 	/**

package/src/gc/gcTelemetry.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import type { Tagged } from "@fluidframework/core-interfaces";
 import { IGarbageCollectionData } from "@fluidframework/runtime-definitions/internal";
 import {
 	ITelemetryLoggerExt,
@@ -12,7 +13,6 @@ import {
 	type ITelemetryGenericEventExt,
 } from "@fluidframework/telemetry-utils/internal";
 
-import type { Tagged } from "@fluidframework/core-interfaces";
 import { RuntimeHeaderData } from "../containerRuntime.js";
 import { ICreateContainerMetadata } from "../summary/index.js";
 

package/src/gc/index.ts

@@ -30,7 +30,6 @@ export {
 	ISweepPhaseStats,
 	IGCStats,
 	oneDayMs,
-	runGCTestKey,
 	runSessionExpiryKey,
 	runSweepKey,
 	stableGCVersion,

package/src/messageTypes.ts

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 
+import { ISequencedDocumentMessage } from "@fluidframework/driver-definitions";
 import type { IdCreationRange } from "@fluidframework/id-compressor/internal";
-import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
 import {
 	IAttachMessage,
 	IEnvelope,

package/src/opLifecycle/README.md

@@ -2,26 +2,28 @@
 
 ## Table of contents
 
--   [Introduction](#introduction)
-    -   [How batching works](#how-batching-works)
--   [Compression](#compression)
--   [Grouped batching](#grouped-batching)
-    -   [Risks](#risks)
--   [Chunking for compression](#chunking-for-compression)
--   [Disabling in case of emergency](#disabling-in-case-of-emergency)
--   [Example configs](#example-configs)
--   [Note about performance and latency](#note-about-performance-and-latency)
--   [How it works](#how-it-works)
--   [How grouped batching works](#how-grouped-batching-works)
--   [How the overall op flow works](#How-the-overall-op-flow-works)
-    -   [Outbound](#outbound)
-    -   [Inbound](#inbound)
+-   [Configs and feature gates for solving the 1MB limit.](#configs-and-feature-gates-for-solving-the-1mb-limit)
+    -   [Table of contents](#table-of-contents)
+    -   [Introduction](#introduction)
+        -   [How batching works](#how-batching-works)
+    -   [Compression](#compression)
+    -   [Grouped batching](#grouped-batching)
+        -   [Changes in op semantics](#changes-in-op-semantics)
+    -   [Chunking for compression](#chunking-for-compression)
+    -   [Disabling in case of emergency](#disabling-in-case-of-emergency)
+    -   [Configuration](#configuration)
+    -   [Note about performance and latency](#note-about-performance-and-latency)
+    -   [How it works](#how-it-works)
+    -   [How it works (Grouped Batching disabled)](#how-it-works-grouped-batching-disabled)
+    -   [How the overall op flow works](#how-the-overall-op-flow-works)
+        -   [Outbound](#outbound)
+        -   [Inbound](#inbound)
 
 ## Introduction
 
 There is a current limitation regarding the size of the payload a Fluid client can send and receive. [The limit is 1MB per payload](https://github.com/microsoft/FluidFramework/issues/9023) and it is currently enforced explicitly with the `BatchTooLarge` error which closes the container.
 
-There are two features which can be used to work around this size limit, batch compression and compressed batch chunking. This document describes how to enable/disable them, along with a brief description of how they work. The features are enabled by default.
+There are three features which can be used to work around this size limit: "grouped batching", "batch compression", and "compressed batch chunking". This document describes how to enable/disable them, along with a brief description of how they work. The features are enabled by default.
 
 By default, the runtime is configured with a max batch size of `716800` bytes, which is lower than the 1MB limit. The reason for the lower value is to account for possible overhead from the op envelope and metadata.
 
@@ -29,7 +31,7 @@ By default, the runtime is configured with a max batch size of `716800` bytes, w
 
 Batching in the context of Fluid ops is a way in which the framework accumulates and applies ops. A batch is a group of ops accumulated within a single JS turn, which will be broadcasted in the same order to all the other connected clients and applied synchronously. Additional logic and validation ensure that batches are never interleaved, nested or interrupted and they are processed in isolation without interleaving of ops from other clients.
 
-The way batches are formed is governed by the `FlushMode` setting of the `ContainerRuntimeOptions` and it is immutable for the entire lifetime of the runtime and subsequently the container.
+The way batches are formed is governed by the `FlushMode` setting of the `IContainerRuntimeOptions` and it is immutable for the entire lifetime of the runtime and subsequently the container.
 
 ```
 export enum FlushMode {
@@ -66,47 +68,30 @@ As `FlushMode.TurnBased` accumulates ops, it is the most vulnerable to run into
 
 Compression is relevant for both `FlushMode.TurnBased` and `FlushMode.Immediate` as it only targets the contents of the ops and not the number of ops in a batch. Compression is opaque to the server and implementations of the Fluid protocol do not need to alter their behavior to support this client feature.
 
-## Grouped batching
-
-The `IContainerRuntimeOptions.enableGroupedBatching` option has been added to the container runtime layer and is **off by default**. This option will group all batch messages under a new "grouped" message to be sent to the service. Upon receiving this new "grouped" message, the batch messages will be extracted and given the sequence number of the parent "grouped" message.
-
-The purpose for enabling grouped batching on top of compression is that regular compression won't include the empty messages in the chunks. Thus, if we have batches with many messages (i.e. more than 4k), we will go over the batch size limit just on empty op envelopes alone.
-
-See [below](#how-grouped-batching-works) for an example.
-
-### Risks
+Compressing a batch yields a batch with the same number of messages. It compresses all the content, shifting the compressed payload into the first op,
+leaving the rest of the batch's messages as empty placeholders to reserve sequence numbers for the compressed messages.
 
-This option should **ONLY** be enabled after observing that 99.9% of your application sessions contains these changes (runtime version "2.0.0-internal.7.0.0" or later). Containers created with this option may not open in future versions of the framework.
-
-This option will change a couple of expectations around message structure and runtime layer expectations. Only enable this option after testing
-and verifying that the following expectation changes won't have any effects:
+## Grouped batching
 
--   batch messages observed at the runtime layer will not match messages seen at the loader layer (i.e. grouped form at loader layer, ungrouped form at runtime layer)
--   messages within the same batch will have the same sequence number
--   client sequence numbers on batch messages can only be used to order messages with the same sequenceNumber
--   requires all ops to be processed by runtime layer (version "2.0.0-internal.1.2.0" or later https://github.com/microsoft/FluidFramework/pull/11832)
+With Grouped Batching enabled (it's on by default), all batch messages are combined under a single "grouped" message _before compression_. Upon receiving this new "grouped" message, the batch messages will be extracted, and they each will be given the same sequence number - that of the parent "grouped" message.
 
-Grouped batching may become problematic for batches which contain reentrant ops. This is the case when changes are made to a DDS inside a DDS 'onChanged' event handler. This means that the reentrant op will have a different reference sequence number than the rest of the ops in the batch, resulting in a different view of the state of the data model.
+The purpose for enabling grouped batching before compression is to eliminate the empty placeholder messages in the chunks. These empty messages are not free to transmit, can trigger service throttling, and in extreme cases can _still_ result in a batch too large (from empty op envelopes alone).
 
-Therefore, when grouped batching is enabled, all batches with reentrant ops are rebased to the current reference sequence number and resubmitted to the data stores so that all ops are in agreement about the state of the data model and ensure eventual consistency.
+Grouped batching is only relevant for `FlushMode.TurnBased`, since `OpGroupingManagerConfig.opCountThreshold` defaults to 2. Grouped batching is opaque to the server and implementations of the Fluid protocol do not need to alter their behavior to support this client feature.
 
-### How to enable
+Grouped Batching can be disabled by setting `IContainerRuntimeOptions.enableGroupedBatching` to `false`.
 
-**This feature is disabled by default**
+See [below](#how-grouped-batching-works) for an example.
 
-If all prerequisites in the previous section are met, enabling the feature can be done via the `IContainerRuntimeOptions` as following:
+### Changes in op semantics
 
-```
-    const runtimeOptions: IContainerRuntimeOptions = {
-        (...)
-        enableGroupedBatching: true,
-        (...)
-    }
-```
+Grouped Batching changed a couple of expectations around message structure and runtime layer expectations. Specifically:
 
-In case of emergency grouped batching can be disabled at runtime, using feature gates. If `"Fluid.ContainerRuntime.DisableGroupedBatching"` is set to `true`, it will disable grouped batching if enabled from `IContainerRuntimeOptions` in the code.
-
-Grouped batching is only relevant for `FlushMode.TurnBased` as it only targets the number of ops in a batch. Grouped batching is opaque to the server and implementations of the Fluid protocol do not need to alter their behavior to support this client feature.
+-   Batch messages observed at the runtime layer no longer match messages seen at the loader layer (i.e. grouped form at loader layer, ungrouped form at runtime layer)
+-   Once the ContainerRuntime ungroups the batch, the client sequence numbers on the resulting messages can only be used to order messages with that batch (having the same sequenceNumber)
+-   Messages within the same batch now all share the same sequence number
+-   All ops in a batch must also have the same reference sequence number to ensure eventualy consistency of the model. The runtime will "rebase" ops in a batch with different ref sequence number to satisfy that requirement.
+    -   What causes ops in a single JS turn (and thus in a batch) to have different reference sequence number? "Op reentrancy", where changes are made to a DDS inside a DDS 'onChanged' event handler.
 
 ## Chunking for compression
 
@@ -120,34 +105,15 @@ Chunking is relevant for both `FlushMode.TurnBased` and `FlushMode.Immediate` as
 
 ## Disabling in case of emergency
 
-If the features are enabled using the configs, they can be disabled at runtime via feature gates as following:
+Compression and Chunking configuration can be overridden via feature gates to force-disable them:
 
 -   `Fluid.ContainerRuntime.CompressionDisabled` - if set to true, will disable compression (this has a side effect of also disabling chunking, as chunking is invoked only for compressed payloads).
--   `Fluid.ContainerRuntime.DisableGroupedBatching` - if set to true, will disable grouped batching.
 -   `Fluid.ContainerRuntime.CompressionChunkingDisabled` - if set to true, will disable chunking for compression.
 
-## Example configs
-
-By default, the runtime is configured with the following values related to compression and chunking:
-
-```
-    const runtimeOptions: IContainerRuntimeOptions = {
-        compressionOptions: {
-            minimumBatchSizeInBytes: 614400,
-            compressionAlgorithm: CompressionAlgorithms.lz4,
-        },
-        chunkSizeInBytes: 204800,
-        maxBatchSizeInBytes: 716800,
-    }
-```
-
-To enable grouped batching, use the following property:
+## Configuration
 
-```
-    const runtimeOptions: IContainerRuntimeOptions = {
-        enableGroupedBatching: true,
-    }
-```
+These features are configured via `IContainerRuntimeOptions`, passed to the `ContainerRuntime.loadRuntime` function.
+Default values are specified in code in [containerRuntime.ts](../containerRuntime.ts).
 
 ## Note about performance and latency
 
@@ -157,86 +123,7 @@ In general, compression offers a trade-off between higher compute costs, lower b
 
 ## How it works
 
-Compression currently works as a runtime layer over the regular op sending/receiving pipeline.
-
-If we have a batch with a size larger than the configured minimum required for compression (in the example let’s say it’s 850 bytes), as following:
-
-```
-+-----------+-----------+-----------+-----------+
-| Op 1      | Op 2      | Op 3      | Op 4      |
-| SeqNum: 1 | SeqNum: 2 | SeqNum: 3 | SeqNum: 4 |
-| Size: 100 | Size: 150 | Size: 200 | Size: 400 |
-+-----------+-----------+-----------+-----------+
-```
-
-The total size of the batch is 850 bytes. The client which needs to send the batch would compress the batch to a smaller size (200 bytes) and will send a new batch like the following:
-
-```
-+--------------------+-----------+-----------+-----------+
-| Op 1               | Op 2      | Op 3      | Op 4      |
-| SeqNum: 1          | SeqNum: 2 | SeqNum: 3 | SeqNum: 4 |
-| Size: 200          | Size: 0   | Size: 0   | Size: 0   |
-| Compression: 'lz4' |           |           |           |
-+--------------------+-----------+-----------+-----------+
-```
-
-The first op in the batch is the only one with content (which is opaque due to it being compressed), the rest of the ops serve only to reserve the sequence numbers so that the state machine which rebuilds the original batch on the receiving client can reconstruct the original batch.
-
-When the batch is received by a client, it will detect the first op as being compressed, it will decompress it and store it in memory. For each empty op subsequently received, it will fetch the uncompressed content from memory and rebuild the original ops. The original ops are then processed by the runtime and applied accordingly.
-So, compression virtualizes the batch.
-
-After compression, the first op in the batch can exceed 1MB, therefore it would still be rejected. In this case, another layer of virtualization is added after compression (and before decompression, symmetrically on the receiving end).
-
-The first op in the compressed batch can be chunked into smaller ops which can be sent outside the original batch. However, to conveniently maintain the batch semantics, the last chunk (the chunk which triggers rebuilding the original op) is the first op in the new batch.
-
-To illustrate, let’s take the large batch below:
-
-```
-+--------------------+-----------+-----------+-----------+
-| Op 1               | Op 2      | Op 3      | Op 4      |
-| SeqNum: 1          | SeqNum: 2 | SeqNum: 3 | SeqNum: 4 |
-| Size: 900          | Size: 0   | Size: 0   | Size: 0   |
-| Compression: 'lz4' |           |           |           |
-+--------------------+-----------+-----------+-----------+
-```
-
-This will produce the following batches:
-
-```
-+-----------+
-| Chunk 1/3 |
-| SeqNum: 1 |
-| Size: 300 |
-+-----------+
-
-```
-
-```
-+-----------+
-| Chunk 2/3 |
-| SeqNum: 2 |
-| Size: 300 |
-+-----------+
-
-```
-
-```
-+-----------+-----------+-----------+-----------+
-| Chunk 3/3 | Op 2      | Op 3      | Op 4      |
-| SeqNum: 3 | SeqNum: 4 | SeqNum: 5 | SeqNum: 6 |
-| Size: 300 | Size: 0   | Size: 0   | Size: 0   |
-+-----------+-----------+-----------+-----------+
-```
-
-The first 2 chunks are sent in their own batches, while the last chunk is the first op in the last batch which contains the ops reserving the required sequence numbers.
-
-Notice that the sequence numbers don’t matter here, as all ops will be based off the same reference sequence number, so the sequence number will be recalculated for all, without additional work.
-
-Additionally, as compression preserves the original uncompressed batch layout in terms of the number of ops by using empty ops to reserve the sequence numbers, this ensures that the clients will always receive the exact count of ops to rebuild the uncompressed batch sequentially.
-
-On the receiving end, the client will accumulate chunks 1 and 2 and keep them in memory. When chunk 3 is received, the original large, decompressed op will be rebuilt, and the runtime will then process the batch as if it is a compressed batch.
-
-## How grouped batching works
+Virtualization works as an intermediate step in the Runtime layer, as the closest step to sending/receiving ops via the Loader layer.
 
 Given the following baseline batch:
 
@@ -262,9 +149,9 @@ Compressed batch:
 
 ```
 +-------------------------------------------------------------------------------------------------------------------------+
-| Op 1                   Contents: +------------------------------------------------------------------------------------+ |
-| Compression: 'lz4'               | Type: "groupedBatch"                                                               | |
-|                                  | +----------------+---------------+---------------+---------------+---------------+ | |
+| Op 1                   Logical   +------------------------------------------------------------------------------------+ |
+| Compression: 'lz4'     Contents: | Type: "groupedBatch"                                                               | |
+| Compressed buffer: "wxyz"        | +----------------+---------------+---------------+---------------+---------------+ | |
 |                                  | | Op 1           | Op 2          | Op 3          | Op 4          | Op 5          | | |
 |                                  | | Contents: "a"  | Contents: "b" | Contents: "c" | Contents: "d" | Contents: "e" | | |
 |                                  | +----------------+---------------+---------------+---------------+---------------+ | |
@@ -278,7 +165,7 @@ Can produce the following chunks:
 +------------------------------------------------+
 | Chunk 1/2    Contents: +---------------------+ |
 |                        | +-----------------+ | |
-|                        | | Contents: "abc" | | |
+|                        | | Contents: "wx" | | |
 |                        | +-----------------+ | |
 |                        +---------------------+ |
 +------------------------------------------------+
@@ -288,16 +175,16 @@ Can produce the following chunks:
 +-----------------------------------------------+
 | Chunk 2/2    Contents: +--------------------+ |
 |                        | +----------------+ | |
-|                        | | Contents: "de" | | |
+|                        | | Contents: "yz" | | |
 |                        | +----------------+ | |
 |                        +--------------------+ |
 +-----------------------------------------------+
 ```
 
--   Send to service
--   Service acks ops sent
--   Receive chunks from service
--   Recompile to the compression step
+The chunks are sent to service to be sequenced, and broadcast to all clients.
+
+-   On the receiving end, the client will accumulate chunks 1 through n-1 and keep them in memory (in this example, it's just Chunk 1).
+-   When the final chunk is received, the original large, decompressed op will be rebuilt, and the runtime will then process the batch as if it is a compressed batch.
 
 Decompressed batch:
 
@@ -321,6 +208,79 @@ Ungrouped batch:
 +-----------------+-----------------+-----------------+-----------------+-----------------+
 ```
 
+## How it works (Grouped Batching disabled)
+
+If we have a batch with a size larger than the configured minimum required for compression (in the example let’s say it’s 850 bytes), as following:
+
+```
++-----------+-----------+-----------+-----------+
+| Op 1      | Op 2      | Op 3      | Op 4      |
+| SeqNum: 1 | SeqNum: 2 | SeqNum: 3 | SeqNum: 4 |
+| Size: 100 | Size: 150 | Size: 200 | Size: 400 |
++-----------+-----------+-----------+-----------+
+```
+
+The total size of the batch is 850 bytes. The client which needs to send the batch would compress the batch to a smaller size (200 bytes) and will send a new batch like the following:
+
+```
++--------------------+-----------+-----------+-----------+
+| Op 1               | Op 2      | Op 3      | Op 4      |
+| SeqNum: 1          | SeqNum: 2 | SeqNum: 3 | SeqNum: 4 |
+| Size: 200          | Size: 0   | Size: 0   | Size: 0   |
+| Compression: 'lz4' |           |           |           |
++--------------------+-----------+-----------+-----------+
+```
+
+The first op in the batch is the only one with content (which is opaque due to it being compressed), the rest of the ops serve only to reserve the sequence numbers so that the state machine which rebuilds the original batch on the receiving client can reconstruct the original batch.
+
+When the batch is received by a client, it will detect the first op as being compressed, it will decompress it and store it in memory. For each empty op subsequently received, it will fetch the uncompressed content from memory and rebuild the original ops. The original ops are then processed by the runtime and applied accordingly.
+So, compression virtualizes the batch.
+
+After compression, the first op in the batch can exceed 1MB, therefore it would still be rejected. In this case, another layer of virtualization is added after compression (and before decompression, symmetrically on the receiving end).
+
+The first op in the compressed batch can be chunked into smaller ops which can be sent outside the original batch. However, to conveniently maintain the batch semantics, the last chunk (the chunk which triggers rebuilding the original op) is the first op in the new batch.
+
+To illustrate, let’s take the large batch below:
+
+```
++--------------------+-----------+-----------+-----------+
+| Op 1               | Op 2      | Op 3      | Op 4      |
+| SeqNum: 1          | SeqNum: 2 | SeqNum: 3 | SeqNum: 4 |
+| Size: 900          | Size: 0   | Size: 0   | Size: 0   |
+| Compression: 'lz4' |           |           |           |
++--------------------+-----------+-----------+-----------+
+```
+
+This will produce the following batches:
+
+```
++-----------+
+| Chunk 1/3 |
+| SeqNum: 1 |
+| Size: 300 |
++-----------+
+
+```
+
+```
++-----------+
+| Chunk 2/3 |
+| SeqNum: 2 |
+| Size: 300 |
++-----------+
+
+```
+
+```
++-----------+-----------+-----------+-----------+
+| Chunk 3/3 | Op 2      | Op 3      | Op 4      |
+| SeqNum: 3 | SeqNum: 4 | SeqNum: 5 | SeqNum: 6 |
+| Size: 300 | Size: 0   | Size: 0   | Size: 0   |
++-----------+-----------+-----------+-----------+
+```
+
+The first 2 chunks are sent in their own batches, while the last chunk is the first op in the last batch which contains the ops reserving the required sequence numbers.
+
 ## How the overall op flow works
 
 ### Outbound

package/src/opLifecycle/definitions.ts

@@ -19,7 +19,7 @@ export type BatchMessage = IBatchMessage & {
 /**
  * Batch interface used internally by the runtime.
  */
-export interface IBatch {
+export interface IBatch<TMessages extends BatchMessage[] = BatchMessage[]> {
 	/**
 	 * Sum of the in-memory content sizes of all messages in the batch.
 	 * If the batch is compressed, this number reflects the post-compression size.
@@ -28,7 +28,7 @@ export interface IBatch {
 	/**
 	 * All the messages in the batch
 	 */
-	readonly content: BatchMessage[];
+	readonly content: TMessages;
 	/**
 	 * The reference sequence number for the batch
 	 */

package/src/opLifecycle/opCompressor.ts

@@ -26,6 +26,13 @@ export class OpCompressor {
 		this.logger = createChildLogger({ logger, namespace: "OpCompressor" });
 	}
 
+	/**
+	 * Combines the contents of the batch into a single JSON string and compresses it, putting
+	 * the resulting string as the first message of the batch. The rest of the messages are
+	 * empty placeholders to reserve sequence numbers.
+	 * @param batch - The batch to compress
+	 * @returns A batch of the same length as the input batch, containing a single compressed message followed by empty placeholders
+	 */
 	public compressBatch(batch: IBatch): IBatch {
 		assert(
 			batch.contentSizeInBytes > 0 && batch.content.length > 0,
@@ -33,7 +40,7 @@ export class OpCompressor {
 		);
 
 		const compressionStart = Date.now();
-		const contentsAsBuffer = new TextEncoder().encode(this.serializeBatch(batch));
+		const contentsAsBuffer = new TextEncoder().encode(this.serializeBatchContents(batch));
 		const compressedContents = compress(contentsAsBuffer);
 		const compressedContent = IsoBuffer.from(compressedContents).toString("base64");
 		const duration = Date.now() - compressionStart;
@@ -75,8 +82,12 @@ export class OpCompressor {
 		return compressedBatch;
 	}
 
-	private serializeBatch(batch: IBatch): string {
+	/**
+	 * Combine the batch's content strings into a single JSON string (a serialized array)
+	 */
+	private serializeBatchContents(batch: IBatch): string {
 		try {
+			// Yields a valid JSON array, since each message.contents is already serialized to JSON
 			return `[${batch.content.map((message) => message.contents).join(",")}]`;
 		} catch (e: any) {
 			if (e.message === "Invalid string length") {

package/src/opLifecycle/opDecompressor.ts

@@ -6,7 +6,7 @@
 import { IsoBuffer, Uint8ArrayToString } from "@fluid-internal/client-utils";
 import { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
-import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+import { ISequencedDocumentMessage } from "@fluidframework/driver-definitions";
 import { createChildLogger } from "@fluidframework/telemetry-utils/internal";
 import { decompress } from "lz4js";
 

package/src/opLifecycle/opGroupingManager.ts

@@ -5,10 +5,10 @@
 
 import { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
-import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+import { ISequencedDocumentMessage } from "@fluidframework/driver-definitions";
 import { createChildLogger } from "@fluidframework/telemetry-utils/internal";
 
-import { IBatch } from "./definitions.js";
+import { IBatch, type BatchMessage } from "./definitions.js";
 
 /**
  * Grouping makes assumptions about the shape of message contents. This interface codifies those assumptions, but does not validate them.
@@ -49,7 +49,14 @@ export class OpGroupingManager {
 		this.logger = createChildLogger({ logger, namespace: "OpGroupingManager" });
 	}
 
-	public groupBatch(batch: IBatch): IBatch {
+	/**
+	 * Converts the given batch into a "grouped batch" - a batch with a single message of type "groupedBatch",
+	 * with contents being an array of the original batch's messages.
+	 *
+	 * @remarks - Remember that a BatchMessage has its content JSON serialized, so the incoming batch message contents
+	 * must be parsed first, and then the type and contents mentioned above are hidden in that JSON serialization.
+	 */
+	public groupBatch(batch: IBatch): IBatch<[BatchMessage]> {
 		assert(this.shouldGroup(batch), 0x946 /* cannot group the provided batch */);
 
 		if (batch.content.length >= 1000) {
@@ -82,7 +89,7 @@ export class OpGroupingManager {
 			})),
 		});
 
-		const groupedBatch: IBatch = {
+		const groupedBatch: IBatch<[BatchMessage]> = {
 			...batch,
 			content: [
 				{