@fluidframework/container-runtime 2.118.0 → 3.0.0

package/src/versionMarks/inboundBatch.ts

@@ -12,10 +12,15 @@ import { getEffectiveBatchId, type InboundMessageResult } from "../opLifecycle/i
  */
 export interface InboundVersionMarkUpdate {
 	/**
-	 * A completed batch to record via `processInboundBatch`: its id and its last op's sequence number.
-	 * Undefined when no batch completed on this message (a piecemeal batch still in progress).
+	 * A completed batch to record via `processInboundBatch`: its id and its last op's sequence
+	 * number and timestamp. Undefined when no batch completed on this message (a piecemeal batch
+	 * still in progress).
 	 */
-	readonly sequenced?: { readonly batchId: string; readonly sequenceNumber: number };
+	readonly sequenced?: {
+		readonly batchId: string;
+		readonly sequenceNumber: number;
+		readonly timestamp: number;
+	};
 	/**
 	 * The batch id to carry for a piecemeal batch still in progress, or undefined when none is pending.
 	 * The caller stores this and passes it back on the next inbound result.
@@ -25,10 +30,10 @@ export interface InboundVersionMarkUpdate {
 
 /**
  * Maps an inbound batch result to the version-mark resolver update. A batch's resolved point is its last
- * op's sequence number, so this reports `(batchId, sequenceNumber)` only once a batch completes. It handles
- * both a batch delivered whole (`fullBatch`, incl. an empty grouped batch via the batch-start key message)
- * and one delivered piecemeal (`batchStartingMessage` then `nextBatchMessage` with `batchEnd`), carrying the
- * batch id across the piecemeal messages via `carriedBatchId`.
+ * op's sequence number and timestamp, so this reports `(batchId, sequenceNumber, timestamp)` only once a
+ * batch completes. It handles both a batch delivered whole (`fullBatch`, incl. an empty grouped batch via
+ * the batch-start key message) and one delivered piecemeal (`batchStartingMessage` then `nextBatchMessage`
+ * with `batchEnd`), carrying the batch id across the piecemeal messages via `carriedBatchId`.
  *
  * @internal
  */
@@ -45,7 +50,11 @@ export function inboundVersionMarkUpdate(
 				inboundResult.messages[inboundResult.messages.length - 1] ??
 				inboundResult.batchStart.keyMessage;
 			return {
-				sequenced: { batchId, sequenceNumber: lastMessage.sequenceNumber },
+				sequenced: {
+					batchId,
+					sequenceNumber: lastMessage.sequenceNumber,
+					timestamp: lastMessage.timestamp,
+				},
 				carriedBatchId: undefined,
 			};
 		}
@@ -61,6 +70,7 @@ export function inboundVersionMarkUpdate(
 			sequenced: {
 				batchId: carriedBatchId,
 				sequenceNumber: inboundResult.nextMessage.sequenceNumber,
+				timestamp: inboundResult.nextMessage.timestamp,
 			},
 			carriedBatchId: undefined,
 		};

package/src/versionMarks/versionMarkResolver.ts

@@ -12,7 +12,6 @@ import { assert } from "@fluidframework/core-utils/internal";
 import type { TelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 
 import type { InboundMessageResult } from "../opLifecycle/index.js";
-import { asBatchMetadata } from "../metadata.js";
 
 import { inboundVersionMarkUpdate } from "./inboundBatch.js";
 
@@ -31,12 +30,17 @@ export interface IHistoricalOpReader {
 }
 
 /**
- * Result of resolving a pending batchId.
+ * Result of resolving a pending batchId. A resolved result includes the matched batch's last op server
+ * timestamp when available. The property is optional for compatibility with previously stored results.
  *
  * @legacy @beta
  */
 export type ResolveResult =
-	| { readonly kind: "resolved"; readonly sequenceNumber: number }
+	| {
+			readonly kind: "resolved";
+			readonly sequenceNumber: number;
+			readonly timestamp?: number;
+	  }
 	| { readonly kind: "pending" }
 	| { readonly kind: "unresolvable" };
 
@@ -54,7 +58,11 @@ export type VersionMarkCapture =
 			readonly batchId: string;
 			readonly sequenceNumberLowerBound: number;
 	  }
-	| { readonly kind: "resolved"; readonly sequenceNumber: number };
+	| {
+			readonly kind: "resolved";
+			readonly sequenceNumber: number;
+			readonly timestamp?: number;
+	  };
 
 /**
  * Runtime-owned resolver for app-stored version mark locators.
@@ -66,34 +74,40 @@ export interface IVersionMarkResolver {
 	 * Captures a version mark at the current point. Seals the current outbound batch first (so a just-made
 	 * local edit has a stable `batchId`, which is only assigned when a batch is flushed), then returns the
 	 * mark data atomically: a `pending` capture (`batchId` + `sequenceNumberLowerBound`) when there is an
-	 * unacked local batch, or a `resolved` capture (`sequenceNumber`) when there is no in-flight local work.
+	 * unacked local batch, or a `resolved` capture (`sequenceNumber` + the last processed op's server
+	 * `timestamp`) when there is no in-flight local work. The timestamp property is optional both for
+	 * compatibility with previously stored captures and because it is `undefined` when neither a last
+	 * processed message nor a last-summary message is available.
 	 *
 	 * @remarks Sealing the batch is a side effect (it submits the current batch), so capture at savepoint
 	 * boundaries, not per keystroke.
 	 *
-	 * @returns The pending batch identity and exclusive sequence number lower bound, or the current sequence number
-	 * when there is no pending local batch.
+	 * @returns The pending batch identity and inclusive sequence number lower bound, or the current sequence
+	 * number and corresponding op timestamp (when available) when there is no pending local batch.
 	 */
 	sealAndCaptureVersionMark(): VersionMarkCapture;
 	/**
 	 * Resolves a pending mark's batchId to a global sequence number (`sequenceNumberLowerBound` is the
-	 * exclusive lower bound for a history read). A `resolved` sequence number feeds the loader's
+	 * inclusive lower bound for a history read). A `resolved` sequence number feeds the loader's
 	 * `loadContainerToSequenceNumber`.
 	 *
 	 * @param batchId - The stable identity of the pending batch.
-	 * @param sequenceNumberLowerBound - The exclusive lower bound for the historical op search.
-	 * @returns The resolved sequence number, or a result indicating that the batch remains pending or can
-	 * no longer be resolved.
+	 * @param sequenceNumberLowerBound - The inclusive lower bound for the historical op search.
+	 * @returns The resolved sequence number and server timestamp, or a result indicating that the batch
+	 * remains pending or can no longer be resolved.
 	 */
 	resolve(batchId: string, sequenceNumberLowerBound: number): Promise<ResolveResult>;
 	/**
-	 * Subscribes to inbound batch sequencing: fires `(batchId, sequenceNumber)` per batch so any connected
-	 * client can promote a matching pending mark. Returns an unsubscribe function.
+	 * Subscribes to inbound batch sequencing: fires `(batchId, sequenceNumber, timestamp)` per batch so any
+	 * connected client can promote a matching pending mark. Returns an unsubscribe function.
 	 *
-	 * @param listener - Called with the stable batch identity and its final sequence number.
+	 * @param listener - Called with the stable batch identity, its final sequence number, and the final op's
+	 * server timestamp.
 	 * @returns A function that unsubscribes the listener.
 	 */
-	onBatchSequenced(listener: (batchId: string, sequenceNumber: number) => void): () => void;
+	onBatchSequenced(
+		listener: (batchId: string, sequenceNumber: number, timestamp?: number) => void,
+	): () => void;
 }
 
 /**
@@ -101,6 +115,7 @@ export interface IVersionMarkResolver {
  */
 export interface VersionMarkResolverRuntimeHooks {
 	readonly getCurrentSequenceNumber: () => number;
+	readonly getCurrentTimestamp: () => number | undefined;
 	readonly getCurrentMinimumSequenceNumber: () => number;
 	readonly getCurrentPendingBatchId: () => string | undefined;
 	/** Logs faults from app-supplied `onBatchSequenced` listeners (see {@link VersionMarkResolver.processInboundBatch}). */
@@ -134,9 +149,12 @@ export interface VersionMarkResolverRuntimeHooks {
  * @internal
  */
 export class VersionMarkResolver implements IVersionMarkResolver {
-	private readonly sequenceNumberByBatchId = new Map<string, number>();
+	private readonly resolvedBatchById = new Map<
+		string,
+		{ readonly sequenceNumber: number; readonly timestamp: number }
+	>();
 	private readonly batchListeners = new Set<
-		(batchId: string, sequenceNumber: number) => void
+		(batchId: string, sequenceNumber: number, timestamp: number) => void
 	>();
 	/**
 	 * Sticky flag: false until the feature is first used this session (a pending capture or a listener).
@@ -156,60 +174,113 @@ export class VersionMarkResolver implements IVersionMarkResolver {
 		// Seal the current batch so a just-submitted local edit is flushed into the pending state with a
 		// stable batchId (which is only assigned at flush) before we read it.
 		this.hooks.flushPendingBatch();
-		const sequenceNumberLowerBound = this.hooks.getCurrentSequenceNumber();
+		const referenceSequenceNumber = this.hooks.getCurrentSequenceNumber();
 		const batchId = this.hooks.getCurrentPendingBatchId();
+		let result: VersionMarkCapture;
 		if (batchId === undefined) {
 			// No unacked local batch: the mark already points at a durable sequence number.
-			return { kind: "resolved", sequenceNumber: sequenceNumberLowerBound };
+			result = {
+				kind: "resolved",
+				sequenceNumber: referenceSequenceNumber,
+				timestamp: this.hooks.getCurrentTimestamp(),
+			};
+		} else {
+			// A pending mark needs its batch tracked so resolve() can promote it from the live map.
+			this.tracking = true;
+			// The pending batch is sequenced after the reference point, so its first possible sequence
+			// number is `referenceSequenceNumber + 1`. Store that as an inclusive lower bound so resolve()
+			// scans directly from it.
+			result = {
+				kind: "pending",
+				batchId,
+				sequenceNumberLowerBound: referenceSequenceNumber + 1,
+			};
 		}
-		// A pending mark needs its batch tracked so resolve() can promote it from the live map.
-		this.tracking = true;
-		return { kind: "pending", batchId, sequenceNumberLowerBound };
+		this.hooks.logger.sendTelemetryEvent({ eventName: "Capture", kind: result.kind });
+		return result;
 	}
 
 	public async resolve(
 		batchId: string,
 		sequenceNumberLowerBound: number,
 	): Promise<ResolveResult> {
-		// Fast path: batch sequenced live this session.
-		const sequenceNumber = this.sessionSequenceFor(batchId);
-		if (sequenceNumber !== undefined) {
-			return { kind: "resolved", sequenceNumber };
-		}
-
-		// Otherwise scan history from the mark's reference point.
-		const reader = this.hooks.getHistoricalOpReader?.();
-		if (reader === undefined) {
-			// No reader: the batch may still sequence live, so report pending.
-			return { kind: "pending" };
+		const startTime = Date.now();
+		// Track from here so inbound batches are recorded even without a prior capture/subscribe; otherwise
+		// a batch sequencing during the scan (or live, in the no-reader case) is skipped and unrecoverable.
+		this.tracking = true;
+		// Defaults cover the throw path (only the history scan can throw — e.g. an unpacker
+		// DataCorruptionError or the 0xd1c reader-contract assert): the Resolve event still fires via
+		// `finally`, with outcome "error".
+		let path: "session" | "history" | "noReader" = "history";
+		let outcome: ResolveResult["kind"] | "error" = "error";
+		let resolvedSequenceNumber: number | undefined;
+		try {
+			// Fast path: batch sequenced live this session.
+			const resolvedBatch = this.sessionResolutionFor(batchId);
+			if (resolvedBatch === undefined) {
+				const reader = this.hooks.getHistoricalOpReader?.();
+				if (reader === undefined) {
+					// No reader: the batch may still sequence live, so report pending.
+					path = "noReader";
+					outcome = "pending";
+					return { kind: "pending" };
+				}
+				// Otherwise scan history from the mark's reference point.
+				path = "history";
+				let result = await this.resolveFromHistory(reader, batchId, sequenceNumberLowerBound);
+				if (result.kind !== "resolved") {
+					// The batch may have sequenced live while the history scan was in progress. Prefer that
+					// authoritative in-session result over a stale history miss.
+					const liveResult = this.sessionResolutionFor(batchId);
+					if (liveResult !== undefined) {
+						path = "session";
+						result = { kind: "resolved", ...liveResult };
+					}
+				}
+				outcome = result.kind;
+				if (result.kind === "resolved") {
+					resolvedSequenceNumber = result.sequenceNumber;
+				}
+				return result;
+			}
+			path = "session";
+			outcome = "resolved";
+			resolvedSequenceNumber = resolvedBatch.sequenceNumber;
+			return { kind: "resolved", ...resolvedBatch };
+		} finally {
+			this.hooks.logger.sendTelemetryEvent({
+				eventName: "Resolve",
+				outcome,
+				path,
+				durationMs: Date.now() - startTime,
+				...(resolvedSequenceNumber === undefined
+					? {}
+					: { sequenceNumber: resolvedSequenceNumber }),
+			});
 		}
-		return this.resolveFromHistory(reader, batchId, sequenceNumberLowerBound);
 	}
 
 	/**
-	 * Scans sequenced ops after `sequenceNumberLowerBound` for `batchId`, returning its last op's
+	 * Scans sequenced ops from `sequenceNumberLowerBound` (inclusive) for `batchId`, returning its last op's
 	 * sequence number when found and aborting the fetch once found or exhausted. Each op is routed through
 	 * the same unpack pipeline the live inbound path uses (chunk reassembly, ungroup, decompress) and
-	 * {@link inboundVersionMarkUpdate} derives its batch identity, so chunked batches resolve here too. The
-	 * scan anchor is not guaranteed to be a batch boundary, so a leading batch clipped by the anchor is
-	 * tolerated (its orphan end marker is dropped rather than fed to the processor). On a miss,
-	 * {@link classifyMiss} distinguishes `pending` (not sequenced yet) from `unresolvable` (ops trimmed).
-	 * See DEV.md.
+	 * {@link inboundVersionMarkUpdate} derives its batch identity, so virtualized batches resolve here too.
+	 * The injected historical unpacker owns virtualization details, including tolerating a requested range
+	 * that begins within an incomplete chunk stream. On a miss, {@link classifyMiss} distinguishes
+	 * `pending` (not sequenced yet) from `unresolvable` (ops trimmed).
 	 */
 	private async resolveFromHistory(
 		reader: IHistoricalOpReader,
 		batchId: string,
 		sequenceNumberLowerBound: number,
 	): Promise<ResolveResult> {
-		const from = sequenceNumberLowerBound + 1;
+		const from = sequenceNumberLowerBound;
 		const unpack = this.hooks.createHistoricalOpUnpacker?.();
 		const abortController = new AbortController();
 		try {
 			const stream = await reader.fetchMessages(from, undefined, abortController.signal);
 			let firstScannedSequenceNumber: number | undefined;
 			let carriedBatchId: string | undefined;
-			// Mirrors the processor's batch-in-progress state so we can drop an orphan end marker (below).
-			let inBatch = false;
 			while (true) {
 				const result = await stream.read();
 				if (result.done) {
@@ -217,32 +288,21 @@ export class VersionMarkResolver implements IVersionMarkResolver {
 				}
 				for (const op of result.value) {
 					firstScannedSequenceNumber ??= op.sequenceNumber;
-					if (!inBatch && asBatchMetadata(op.metadata)?.batch === false) {
-						// The anchor (`sequenceNumberLowerBound + 1`) may land inside a batch whose start
-						// precedes the window; its orphan end marker would trip the processor's 0x9d5 assert.
-						// Drop the clipped tail. The target batch is fully in-window, so this can't skip it.
-						continue;
-					}
-					// undefined = a system op, or an incomplete chunk awaiting later fragments.
+					// undefined = a system op or virtualized input that has not produced a complete result.
 					const inboundResult = unpack?.(op);
 					if (inboundResult === undefined) {
 						continue;
 					}
-					// Track batch progress with the processor so the guard above skips only orphan ends.
-					if (inboundResult.type === "batchStartingMessage") {
-						inBatch = true;
-					} else if (
-						inboundResult.type === "nextBatchMessage" &&
-						inboundResult.batchEnd === true
-					) {
-						inBatch = false;
-					}
 					// Derive batch identity exactly as the live inbound path does, carrying the id across a
 					// piecemeal batch's messages.
 					const update = inboundVersionMarkUpdate(inboundResult, carriedBatchId);
 					carriedBatchId = update.carriedBatchId;
 					if (update.sequenced?.batchId === batchId) {
-						return { kind: "resolved", sequenceNumber: update.sequenced.sequenceNumber };
+						return {
+							kind: "resolved",
+							sequenceNumber: update.sequenced.sequenceNumber,
+							timestamp: update.sequenced.timestamp,
+						};
 					}
 				}
 			}
@@ -269,7 +329,7 @@ export class VersionMarkResolver implements IVersionMarkResolver {
 		);
 		const tip = this.hooks.getCurrentSequenceNumber();
 		if (from > tip) {
-			// Nothing is sequenced at/after the mark's reference point yet, so the batch cannot have landed.
+			// Nothing is sequenced at/after the mark's lower bound yet, so the batch cannot have landed.
 			return { kind: "pending" };
 		}
 		if (firstScannedSequenceNumber === undefined) {
@@ -279,15 +339,15 @@ export class VersionMarkResolver implements IVersionMarkResolver {
 			return { kind: "unresolvable" };
 		}
 		if (firstScannedSequenceNumber > from) {
-			// A trim gap at the anchor: the mark's ops (just after the reference point) are gone.
+			// A trim gap at the anchor: the mark's ops (at/after its lower bound) are gone.
 			return { kind: "unresolvable" };
 		}
-		// Ops are present from the reference point and the batch is not among them: not yet sequenced.
+		// Ops are present from the lower bound and the batch is not among them: not yet sequenced.
 		return { kind: "pending" };
 	}
 
 	public onBatchSequenced(
-		listener: (batchId: string, sequenceNumber: number) => void,
+		listener: (batchId: string, sequenceNumber: number, timestamp?: number) => void,
 	): () => void {
 		// A subscriber wants live promotions, so start tracking inbound batches from here on.
 		this.tracking = true;
@@ -297,23 +357,32 @@ export class VersionMarkResolver implements IVersionMarkResolver {
 		};
 	}
 
-	/** The sequence number for a batch seen live this session, or undefined. */
-	private sessionSequenceFor(batchId: string): number | undefined {
-		return this.sequenceNumberByBatchId.get(batchId);
+	/** The resolved point for a batch seen live this session, or undefined. */
+	private sessionResolutionFor(
+		batchId: string,
+	): { readonly sequenceNumber: number; readonly timestamp: number } | undefined {
+		return this.resolvedBatchById.get(batchId);
 	}
 
 	/** Records an inbound batch and notifies listeners so any client can promote matching pending marks. */
-	public processInboundBatch(batchId: string, sequenceNumber: number): void {
-		const existingSequenceNumber = this.sequenceNumberByBatchId.get(batchId);
-		if (existingSequenceNumber === sequenceNumber) {
+	public processInboundBatch(
+		batchId: string,
+		sequenceNumber: number,
+		timestamp: number,
+	): void {
+		const existingResolution = this.resolvedBatchById.get(batchId);
+		if (existingResolution !== undefined) {
+			// NOTE: It's possible (but exceedingly rare) that this is a spurious duplicated batch,
+			// with a different sequence number/timestamp.
+			// Rather than asserting or overwriting, we let the earlier version mark stand, it is sufficient.
 			return;
 		}
 
-		this.sequenceNumberByBatchId.set(batchId, sequenceNumber);
+		this.resolvedBatchById.set(batchId, { sequenceNumber, timestamp });
 		this.evictBelowMinimumSequenceNumber();
 		for (const listener of this.batchListeners) {
 			try {
-				listener(batchId, sequenceNumber);
+				listener(batchId, sequenceNumber, timestamp);
 			} catch (error) {
 				// Isolate each app listener (like the container's EventEmitterWithErrorHandling): one throw
 				// must not abort op processing or starve the rest. Log and continue rather than fault the
@@ -331,11 +400,11 @@ export class VersionMarkResolver implements IVersionMarkResolver {
 	 */
 	private evictBelowMinimumSequenceNumber(): void {
 		const minimumSequenceNumber = this.hooks.getCurrentMinimumSequenceNumber();
-		for (const [id, sequenceNumber] of this.sequenceNumberByBatchId) {
-			if (sequenceNumber >= minimumSequenceNumber) {
+		for (const [id, resolution] of this.resolvedBatchById) {
+			if (resolution.sequenceNumber >= minimumSequenceNumber) {
 				break;
 			}
-			this.sequenceNumberByBatchId.delete(id);
+			this.resolvedBatchById.delete(id);
 		}
 	}
 }

package/tsconfig.json

@@ -1,5 +1,5 @@
 {
-	"extends": "../../../common/build/build-common/tsconfig.node16.json",
+	"extends": "../../../common/build/build-common/tsconfig.node20.json",
 	"include": ["src/**/*"],
 	"exclude": ["src/test/**/*"],
 	"compilerOptions": {

package/internal.d.ts

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outFileLegacyAlpha legacyAlpha --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
- */
-
-export * from "./lib/index.js";

package/legacy/alpha.d.ts

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outFileLegacyAlpha legacyAlpha --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
- */
-
-export * from "../lib/legacyAlpha.js";

package/legacy.d.ts

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outFileLegacyAlpha legacyAlpha --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
- */
-
-export * from "./lib/legacy.js";