@fluidframework/container-loader 2.117.0 → 3.0.0

package/src/loaderLayerCompatState.ts

@@ -5,6 +5,7 @@
 
 import {
 	generation,
+	defaultLayerCompatDetails,
 	LayerCompatibilityPolicyWindowMonths,
 	type ILayerCompatDetails,
 	type ILayerCompatSupportRequirements,
@@ -44,6 +45,18 @@ export const loaderCompatDetailsForRuntime: ILayerCompatDetails = {
 	supportedFeatures: new Set<string>(),
 };
 
+/**
+ * Loader's compatibility details that is validated against the Driver layer's requirements.
+ * @internal
+ */
+export const loaderCompatDetailsForDriver: ILayerCompatDetails = {
+	...loaderCoreCompatDetails,
+	/**
+	 * The features supported by the Loader layer across the Loader / Driver boundary.
+	 */
+	supportedFeatures: new Set<string>(),
+};
+
 /**
  * The requirements that the Runtime layer must meet to be compatible with this Loader.
  * @internal
@@ -51,13 +64,14 @@ export const loaderCompatDetailsForRuntime: ILayerCompatDetails = {
 export const runtimeSupportRequirementsForLoader: ILayerCompatSupportRequirements = {
 	/**
 	 * Minimum generation that Runtime must be at to be compatible with this Loader. This is calculated
-	 * based on the LayerCompatibilityPolicyWindowMonths.LoaderRuntime value which defines how many months old can
-	 * the Runtime layer be compared to the Loader layer for them to still be considered compatible.
+	 * based on the LayerCompatibilityPolicyWindowMonths.NewLoaderOldRuntime value which defines how many months
+	 * old can the Runtime layer be compared to the Loader layer for them to still be considered compatible.
 	 * The minimum valid generation value is 0.
 	 */
 	minSupportedGeneration: Math.max(
 		0,
-		loaderCoreCompatDetails.generation - LayerCompatibilityPolicyWindowMonths.LoaderRuntime,
+		loaderCoreCompatDetails.generation -
+			LayerCompatibilityPolicyWindowMonths.NewLoaderOldRuntime,
 	),
 	/**
 	 * The features that the Runtime must support to be compatible with Loader.
@@ -72,13 +86,14 @@ export const runtimeSupportRequirementsForLoader: ILayerCompatSupportRequirement
 export const driverSupportRequirementsForLoader: ILayerCompatSupportRequirements = {
 	/**
 	 * Minimum generation that Driver must be at to be compatible with this Loader. This is calculated
-	 * based on the LayerCompatibilityPolicyWindowMonths.LoaderDriver value which defines how many months old can
-	 * the Driver layer be compared to the Loader layer for them to still be considered compatible.
+	 * based on the LayerCompatibilityPolicyWindowMonths.NewLoaderOldDriver value which defines how many months
+	 * old can the Driver layer be compared to the Loader layer for them to still be considered compatible.
 	 * The minimum valid generation value is 0.
 	 */
 	minSupportedGeneration: Math.max(
 		0,
-		loaderCoreCompatDetails.generation - LayerCompatibilityPolicyWindowMonths.LoaderDriver,
+		loaderCoreCompatDetails.generation -
+			LayerCompatibilityPolicyWindowMonths.NewLoaderOldDriver,
 	),
 	/**
 	 * The features that the Driver must support to be compatible with Loader.
@@ -95,13 +110,19 @@ export function validateRuntimeCompatibility(
 	mc: MonitoringContext,
 ): void {
 	validateLayerCompatibility(
-		"loader",
-		"runtime",
-		loaderCompatDetailsForRuntime,
-		runtimeSupportRequirementsForLoader,
-		maybeRuntimeCompatDetails,
-		() => {} /* disposeFn - no op. This will be handled by the caller */,
-		mc,
+		/* validatingLayer */ {
+			layer: "loader",
+			packageInfo: loaderCoreCompatDetails,
+			compatSupportRequirements: runtimeSupportRequirementsForLoader,
+		},
+		/* targetLayer */ {
+			layer: "runtime",
+			compatDetails: maybeRuntimeCompatDetails,
+		},
+		{
+			disposeFn: () => {} /* no op. This will be handled by the caller */,
+			mc,
+		},
 	);
 }
 
@@ -115,12 +136,56 @@ export function validateDriverCompatibility(
 	mc: MonitoringContext,
 ): void {
 	validateLayerCompatibility(
-		"loader",
-		"driver",
-		loaderCompatDetailsForRuntime,
-		driverSupportRequirementsForLoader,
-		maybeDriverCompatDetails,
-		disposeFn,
-		mc,
+		/* validatingLayer */ {
+			layer: "loader",
+			packageInfo: loaderCoreCompatDetails,
+			compatSupportRequirements: driverSupportRequirementsForLoader,
+		},
+		/* targetLayer */ {
+			layer: "driver",
+			compatDetails: maybeDriverCompatDetails,
+		},
+		{ disposeFn, mc },
+	);
+}
+
+/**
+ * Validates that the Loader layer is compatible with the Driver.
+ *
+ * @remarks
+ * This is the reverse of {@link validateDriverCompatibility} and is intentionally a separate function because it
+ * does not follow the standard layer-validation pattern. Normally each layer validates the layer it holds a
+ * reference to - the Loader validates the Driver, the Runtime validates the Loader, and so on. The Driver, however,
+ * has no reference to the Loader and therefore cannot run this validation itself. To still enforce compatibility in
+ * both directions across the Driver / Loader boundary, the Driver publishes the requirements it has for the Loader
+ * (via ILayerCompatSupportRequirements) and the Loader validates itself against them here, on the Driver's behalf.
+ *
+ * @param maybeDriverCompatDetails - The Driver's compatibility details, used only to attribute the version /
+ * generation of the Driver in telemetry if the Loader is found to be incompatible.
+ * @param maybeDriverCompatRequirements - The requirements the Driver has for the Loader. Older Drivers may not
+ * publish these, in which case there is nothing to validate in this direction.
+ *
+ * @internal
+ */
+export function validateLoaderCompatibilityWithDriver(
+	maybeDriverCompatDetails: ILayerCompatDetails | undefined,
+	maybeDriverCompatRequirements: ILayerCompatSupportRequirements | undefined,
+	disposeFn: (error?: ICriticalContainerError) => void,
+	mc: MonitoringContext,
+): void {
+	if (maybeDriverCompatRequirements === undefined) {
+		return;
+	}
+	validateLayerCompatibility(
+		/* validatingLayer */ {
+			layer: "driver",
+			packageInfo: maybeDriverCompatDetails ?? defaultLayerCompatDetails,
+			compatSupportRequirements: maybeDriverCompatRequirements,
+		},
+		/* targetLayer */ {
+			layer: "loader",
+			compatDetails: loaderCompatDetailsForDriver,
+		},
+		{ disposeFn, mc },
 	);
 }

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-loader";
-export const pkgVersion = "2.117.0";
+export const pkgVersion = "3.0.0";

package/src/pendingLocalStateStore.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import type { FluidIterableIterator } from "@fluidframework/core-interfaces";
 import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -140,7 +141,7 @@ export class PendingLocalStateStore<TKey> {
 	/**
 	 * Returns an iterator over [key, serializedState] pairs.
 	 */
-	entries(): Iterator<[TKey, string]> {
+	entries(): FluidIterableIterator<[TKey, string]> {
 		const iterator = this.#pendingStates.entries();
 		return {
 			next: (): IteratorResult<[TKey, string]> => {
@@ -151,20 +152,23 @@ export class PendingLocalStateStore<TKey> {
 				}
 				return { done, value: [value[0], JSON.stringify(value[1])] };
 			},
+			[Symbol.iterator](): FluidIterableIterator<[TKey, string]> {
+				return this;
+			},
 		};
 	}
 
 	/**
 	 * Returns an iterator over the stored keys.
 	 */
-	keys(): IterableIterator<TKey> {
+	keys(): FluidIterableIterator<TKey> {
 		return this.#pendingStates.keys();
 	}
 
 	/**
 	 * Makes the store iterable with `for...of` loops.
 	 */
-	[Symbol.iterator](): Iterator<[TKey, string]> {
+	[Symbol.iterator](): FluidIterableIterator<[TKey, string]> {
 		return this.entries();
 	}
 }

package/src/pointInTime/DEV.md

@@ -9,12 +9,23 @@ This flow consumes a sequence number. It does not create or resolve version mark
 The host calls:
 
 ```ts
+import { createOdspDocumentServiceFactory } from "@fluidframework/odsp-driver/legacy";
+import { createPointInTimeDocumentService } from "@fluidframework/odsp-driver/legacy/point-in-time";
+
+const documentServiceFactory = createOdspDocumentServiceFactory({
+  getStorageToken,
+  getWebsocketToken,
+  persistedCache,
+  hostPolicy,
+  pointInTimeDocumentServiceImplementation: createPointInTimeDocumentService,
+});
+
 const historicalContainer = await loadContainerToSequenceNumber({
 	request,
 	loadToSequenceNumber,
 	codeLoader,
 	urlResolver,
-	documentServiceFactory: getOdspPointInTimeDocumentServiceFactory(/* credentials */),
+  documentServiceFactory,
 	logger,
 	signal,
 });
@@ -76,6 +87,28 @@ That service must satisfy the following:
 
 The loader detects this capability structurally so callers pass the driver's factory directly. The adapter is internal and cannot create new containers.
 
+### Capability typing and validation boundary
+
+The point-in-time capability is not part of the general `IDocumentServiceFactory` contract. Fluid
+therefore owns both runtime checks needed to bridge the optional capability:
+
+- The host imports `createPointInTimeDocumentService` from the dedicated ODSP point-in-time entrypoint
+  and injects it through `createOdspDocumentServiceFactory` options.
+- `asPointInTimeCapableFactory` performs the cross-driver structural check at the loader boundary.
+  `loadContainerToSequenceNumber` uses this check before constructing its internal adapter.
+
+A host should not repeat the capability check or cast a general factory. It passes the configured
+ODSP factory directly to `loadContainerToSequenceNumber`. Keeping detection in Fluid also gives
+non-ODSP drivers one generic loader boundary to satisfy without exposing their implementation details
+to hosts.
+
+If the host-facing orchestration moves to the proposed feature package, the private generic
+capability interface, `asPointInTimeCapableFactory`, and
+`PointInTimeDocumentServiceFactory` move with it. The ODSP public interface, construction helper,
+and implementation remain in `@fluidframework/odsp-driver`. The capability should move into a
+shared driver contract only if multiple drivers need a public compile-time type; structural
+detection is sufficient for the current single-provider alpha API.
+
 ## Package ownership and planned extraction
 
 The current placement in `@fluidframework/container-loader` was explicitly described as
@@ -118,7 +151,7 @@ be regenerated rather than edited by hand.
 | Current owner | What remains | Why |
 | --- | --- | --- |
 | `@fluidframework/container-loader` | `loadContainerPaused` and its general loading machinery | This is the driver-agnostic loader primitive. It predates point-in-time loading and is also used by non-ODSP callers. The feature package should compose it rather than duplicate loader internals. |
-| `@fluidframework/odsp-driver` | `pointInTimeDriver/`, `odspVersionManager/`, and `getOdspPointInTimeDocumentServiceFactory` | These components depend on ODSP file-version APIs, resolved URLs, caches, storage policies, and epoch tracking. Moving them would either leak ODSP internals into the feature package or duplicate driver construction logic. |
+| `@fluidframework/odsp-driver` | The optional point-in-time capability on `OdspDocumentServiceFactoryCore`, `pointInTimeDriver/`, and `odspVersionManager/` | These components depend on ODSP file-version APIs, resolved URLs, caches, storage policies, and epoch tracking. Moving them would either leak ODSP internals into the feature package or duplicate driver construction logic. |
 | `@fluidframework/container-runtime` | `versionMarks/` resolver implementation and runtime hooks | Capture and locator resolution are driver-agnostic but tightly coupled to outbound batching, pending state, inbound processing, and the runtime lifecycle. They produce the sequence number consumed by the feature package; they do not perform historical loading. |
 
 The new package should not import ODSP directly. Its contract remains capability-based so another
@@ -150,7 +183,14 @@ must not make container-loader depend on ODSP or merge mark resolution into cont
 
 ## ODSP implementation
 
-ODSP resolves the closest recoverable driveItem version at or before the target. It then composes:
+`OdspDocumentServiceFactoryCore` exposes the optional `createPointInTimeDocumentService` capability
+only when the consumer supplies an implementation. ODSP owns that implementation in the dedicated
+`@fluidframework/odsp-driver/legacy/point-in-time` entrypoint, while the consumer controls whether the
+feature enters its dependency graph. The consumer injects the implementation through
+`createOdspDocumentServiceFactory` options.
+
+For each point-in-time request, ODSP resolves the closest recoverable driveItem version at or before
+the target. It then composes:
 
 - storage from that file version;
 - bounded delta storage from the live document;
@@ -179,7 +219,10 @@ Like normal storage catch-up, retriable network failures may retry for an extend
 | `loadContainerToSequenceNumber.ts` | Validates the target and driver capability, installs the adapter, and starts the paused load. |
 | `pointInTimeServices.ts` | Defines the structural driver capability and adapts it to `IDocumentServiceFactory`. |
 | `loadPaused.ts` | Loads read-only, replays to the exact target, pauses processing, disconnects, and handles cancellation. |
-| `packages/drivers/odsp-driver/src/pointInTimeDriver/odspPointInTimeDocumentServiceFactory.ts` | Selects the ODSP base version and creates the historical service with shared epoch tracking. |
+| `packages/drivers/odsp-driver/src/odspDocumentServiceFactory.ts` | Accepts and installs a consumer-supplied PIT implementation and constructs a typed capable factory. |
+| `packages/drivers/odsp-driver/src/odspDocumentServiceFactoryCore.ts` | Defines the injection contract and delegates to the implementation only when supplied. |
+| `packages/drivers/odsp-driver/src/pointInTime.ts` | Dedicated consumer-imported feature entrypoint. |
+| `packages/drivers/odsp-driver/src/pointInTimeDriver/createPointInTimeDocumentService.ts` | Owns ODSP base selection, shared epoch tracking, and historical/live service composition. |
 | `packages/drivers/odsp-driver/src/pointInTimeDriver/odspPointInTimeDocumentService.ts` | Recombines historical storage with bounded live delta storage and enforces storage-only behavior. |
 
 ## Test map

package/src/serializedStateManager.ts

@@ -75,6 +75,12 @@ export interface IPendingContainerState extends SnapshotWithBlobs {
 	 * This container was attached (as opposed to IPendingDetachedContainerState.attached which is false)
 	 */
 	attached: true;
+	/**
+	 * Indicates that blob payloads are omitted and must be read from live storage.
+	 *
+	 * Undefined for existing and self-contained pending state.
+	 */
+	blobContentsMode?: "reference";
 	/**
 	 * Runtime-specific state that will be needed to properly rehydrate
 	 * (it's included in ContainerContext passed to instantiateRuntime)

package/src/utils.ts

@@ -6,7 +6,7 @@
 import {
 	bufferToString,
 	stringToBuffer,
-	Uint8ArrayToArrayBuffer,
+	AnyUint8ArrayToArrayBuffer,
 } from "@fluid-internal/client-utils";
 import { assert, compareArrays, unreachableCase } from "@fluidframework/core-utils/internal";
 import { type ISummaryTree, SummaryType } from "@fluidframework/driver-definitions";
@@ -75,7 +75,7 @@ export interface IParsedUrl {
  * Utility api to parse the IResolvedUrl.url into specific parts like querystring, path to get
  * deep link info etc.
  * Warning - This function may not be compatible with any Url Resolver's resolved url. It works
- * with urls of type: protocol://<string>/.../..?<querystring>
+ * with urls of type: `protocol://{host}/.../..?{queryString}`
  * @param url - This is the IResolvedUrl.url part of the resolved url.
  * @returns The IParsedUrl representing the input URL, or undefined if the format was not supported
  * @legacy @beta
@@ -172,7 +172,7 @@ function convertSummaryToISnapshot(
 				blobContents.set(
 					blobId,
 					summaryObject.content instanceof Uint8Array
-						? Uint8ArrayToArrayBuffer(summaryObject.content)
+						? AnyUint8ArrayToArrayBuffer(summaryObject.content)
 						: stringToBuffer(summaryObject.content, "utf8"),
 				);
 

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";