feat(container-runtime): add groupedOpCount to grouped batch metadata

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

@@ -40,6 +40,20 @@ export interface IBatchMetadata {
 	 * Maybe set on first message of a batch, to the batchId generated when resubmitting (set/fixed on first resubmit)
 	 */
 	batchId?: BatchId;
+	/**
+	 * Set on the envelope of a grouped batch op to the number of inner ops it contains.
+	 * Exposed on the wire so consumers can record batch sizes in telemetry without parsing the grouped batch contents.
+	 *
+	 * Observable values:
+	 * - Absent: this is not a grouped batch envelope (e.g. a singleton batch that bypassed grouping).
+	 * - `0`: empty-grouped-batch placeholder produced when a resubmitted batch becomes empty.
+	 * - `N` (N \> 0): grouped batch with N inner ops. For a chunked grouped batch this appears only on the last chunk's envelope (intermediate chunks carry no metadata).
+	 *
+	 * The field is intentionally advisory-only: the runtime does not validate that an inbound value matches the batch's actual inner op count. It is consumed exclusively by off-runtime telemetry.
+	 *
+	 * The field is always (re)stamped at outbound time from the current batch's actual size — `groupBatch` reads `batch.messages.length` directly, `createEmptyGroupedBatch` always writes `0`, and the chunking path only ever sees freshly-grouped envelopes from the same flush. It is never propagated from stashed pending state to the wire: on resubmit, ops re-enter grouping and the count is recomputed from the (possibly squashed, dropped, or added) outbound batch. This means the wire value always reflects the actual outbound size, even when the resubmitted batch differs from the original.
+	 */
+	groupedOpCount?: number;
 }
 
 /**

packages/runtime/container-runtime/src/opLifecycle/opGroupingManager.ts

@@ -100,7 +100,7 @@ export class OpGroupingManager {
 		const serializedOp = JSON.stringify(emptyGroupedBatch);
 
 		const placeholderMessage: LocalEmptyBatchPlaceholder = {
-			metadata: { batchId: resubmittingBatchId },
+			metadata: { batchId: resubmittingBatchId, groupedOpCount: 0 },
 			localOpMetadata: { emptyBatch: true },
 			referenceSequenceNumber,
 			runtimeOp: emptyGroupedBatch,
@@ -169,7 +169,7 @@ export class OpGroupingManager {
 			...batch,
 			messages: [
 				{
-					metadata: { batchId: groupedBatchId },
+					metadata: { batchId: groupedBatchId, groupedOpCount: batch.messages.length },
 					referenceSequenceNumber: batch.messages[0].referenceSequenceNumber,
 					contents: serializedContent,
 				},

packages/runtime/container-runtime/src/opLifecycle/opSplitter.ts

@@ -171,12 +171,19 @@ export class OpSplitter {
 			);
 		}
 
-		// The last chunk will be part of the new batch and needs to
-		// preserve the batch metadata of the original batch
+		// The last chunk will be part of the new batch and needs to preserve the
+		// batch metadata of the original batch. groupedOpCount is surfaced here
+		// (and only here, not on intermediate chunks) because intermediate chunks
+		// don't carry ops — they carry parts of a payload that only become ops
+		// once the last chunk is processed and the payload is reassembled.
+		// Stamping every chunk would let an observer double-count messages.
 		const lastChunk = chunkToBatchMessage(
 			chunks[chunks.length - 1],
 			batch.referenceSequenceNumber,
-			{ batch: firstMessage.metadata?.batch },
+			{
+				batch: firstMessage.metadata?.batch,
+				groupedOpCount: firstMessage.metadata?.groupedOpCount,
+			},
 		);
 
 		this.logger.sendPerformanceEvent({

packages/runtime/container-runtime/src/test/opLifecycle/OpGroupingManager.spec.ts

@@ -74,7 +74,7 @@ describe("OpGroupingManager", () => {
 				{
 					contents:
 						'{"type":"groupedBatch","contents":[{"contents":0},{"contents":0},{"contents":0},{"contents":0},{"contents":0}]}',
-					metadata: { batchId: undefined },
+					metadata: { batchId: undefined, groupedOpCount: 5 },
 					referenceSequenceNumber: 0,
 				},
 			]);
@@ -90,6 +90,7 @@ describe("OpGroupingManager", () => {
 			).groupBatch(createBatch(5, false, false, batchId));
 			assert.strictEqual(result.messages.length, 1);
 			assert.strictEqual(result.messages[0].metadata?.batchId, batchId);
+			assert.strictEqual(result.messages[0].metadata?.groupedOpCount, 5);
 		});
 
 		it("empty grouped batching disabled", () => {
@@ -111,7 +112,7 @@ describe("OpGroupingManager", () => {
 			const batchId = "batchId";
 			const expectedOutboundMessage: OutboundBatchMessage = {
 				contents: '{"type":"groupedBatch","contents":[]}',
-				metadata: { batchId },
+				metadata: { batchId, groupedOpCount: 0 },
 				localOpMetadata: { emptyBatch: true },
 				referenceSequenceNumber: 0,
 				runtimeOp: undefined,
@@ -128,7 +129,7 @@ describe("OpGroupingManager", () => {
 
 			const expectedPlaceholderMessage: LocalEmptyBatchPlaceholder = {
 				runtimeOp: emptyGroupedBatch,
-				metadata: { batchId },
+				metadata: { batchId, groupedOpCount: 0 },
 				localOpMetadata: { emptyBatch: true },
 				referenceSequenceNumber: 0,
 			};

packages/runtime/container-runtime/src/test/opLifecycle/opCompressor.spec.ts

@@ -41,7 +41,7 @@ describe("OpCompressor", () => {
 		referenceSequenceNumber: messages[0].referenceSequenceNumber,
 	});
 	const createMessage = (contents: string) => ({
-		metadata: { flag: true },
+		metadata: { flag: true, groupedOpCount: 7 },
 		type: ContainerMessageType.FluidDataStoreOp,
 		contents,
 		referenceSequenceNumber: 0,
@@ -63,6 +63,7 @@ describe("OpCompressor", () => {
 				assert.strictEqual(compressedBatch.messages.length, batch.messages.length);
 				assert.strictEqual(compressedBatch.messages[0].compression, "lz4");
 				assert.strictEqual(compressedBatch.messages[0].metadata?.flag, true);
+				assert.strictEqual(compressedBatch.messages[0].metadata?.groupedOpCount, 7);
 			}).timeout(3000);
 		}
 	});

packages/runtime/container-runtime/src/test/opLifecycle/opSplitter.spec.ts

@@ -398,6 +398,73 @@ describe("OpSplitter", () => {
 				);
 			});
 		}
+
+		it("Propagates groupedOpCount onto the last chunk only", () => {
+			const chunkSize = 20;
+			const opSplitter = new OpSplitter(
+				[],
+				mockSubmitBatchFn,
+				chunkSize,
+				maxBatchSizeInBytes,
+				mockLogger,
+			);
+			const groupedOpCount = 7;
+			const largeMessage: OutboundBatchMessage = {
+				...generateChunkableOp(100),
+				metadata: { batch: true, groupedOpCount },
+			};
+
+			const result = opSplitter.splitSingletonBatchMessage({
+				messages: [largeMessage],
+				contentSizeInBytes: largeMessage.contents?.length ?? 0,
+				referenceSequenceNumber: 0,
+			});
+
+			// Intermediate chunks (the ones submitted directly) carry no metadata.
+			for (const submitted of batchesSubmitted) {
+				assert.strictEqual(submitted.messages.length, 1);
+				assert.strictEqual(submitted.messages[0].metadata, undefined);
+			}
+
+			// Last chunk envelope carries both batch flag and groupedOpCount.
+			assert.strictEqual(result.messages.length, 1);
+			assert.deepStrictEqual(result.messages[0].metadata, {
+				batch: true,
+				groupedOpCount,
+			});
+
+			// Reassembly preserves groupedOpCount via originalMetadata on the final chunk's payload.
+			const reassembler = new OpSplitter(
+				[],
+				mockSubmitBatchFn,
+				chunkSize,
+				maxBatchSizeInBytes,
+				mockLogger,
+			);
+			const allChunks = [
+				...batchesSubmitted.map(
+					(b) =>
+						JSON.parse((b.messages[0] as OutboundBatchMessage).contents!) as {
+							contents: IChunkedOp;
+						},
+				),
+				JSON.parse(result.messages[0].contents!) as { contents: IChunkedOp },
+			].map((parsed) => parsed.contents);
+
+			let final: ISequencedDocumentMessage | undefined;
+			for (const chunk of allChunks) {
+				const wrapped = {
+					contents: { type: ContainerMessageType.ChunkedOp, contents: chunk },
+					clientId: "testClient",
+				} as unknown as ISequencedDocumentMessage;
+				const processed = reassembler.processChunk(wrapped);
+				if (processed.isFinalChunk) {
+					final = processed.message;
+				}
+			}
+			assert(final !== undefined, "Expected reassembly to complete");
+			assert.deepStrictEqual(final.metadata, { batch: true, groupedOpCount });
+		});
 	});
 	const assertSameMessage = (
 		result: ISequencedDocumentMessage,