@fluidframework/container-loader 2.116.1 → 2.118.0

package/src/loadContainerToSequenceNumber.ts

@@ -24,8 +24,9 @@ import {
  * This is distinct from normal container loading. The supplied
  * {@link IContainerDriverServices.documentServiceFactory} must be able to materialize the document
  * at {@link ILoadContainerToSequenceNumberProps.loadToSequenceNumber} - i.e. it must implement the
- * point-in-time capability the loader detects. For ODSP, pass an
- * `IPointInTimeDocumentServiceFactory` created by `getOdspPointInTimeDocumentServiceFactory`.
+ * point-in-time capability the loader detects. For ODSP, call
+ * `createOdspDocumentServiceFactory` with the implementation imported from
+ * `@fluidframework/odsp-driver/legacy/point-in-time`.
  *
  * @legacy @beta
  */
@@ -58,9 +59,9 @@ export interface ILoadContainerToSequenceNumberProps
  * The supplied {@link IContainerDriverServices.documentServiceFactory} must support point-in-time
  * loading: it must be able to serve a snapshot at or before
  * {@link ILoadContainerToSequenceNumberProps.loadToSequenceNumber} and replay the document forward
- * through that sequence number. For ODSP, pass the result of
- * `getOdspPointInTimeDocumentServiceFactory` (from `@fluidframework/odsp-driver`) directly - the
- * loader materializes the point-in-time view itself, so no wrapping or decoration is required.
+ * through that sequence number. For ODSP, inject `createPointInTimeDocumentService` from the
+ * dedicated point-in-time entrypoint through `createOdspDocumentServiceFactory` options. The loader
+ * materializes the point-in-time view itself, so no wrapping or decoration is required.
  *
  * @param props - The load options, point-in-time-capable driver services, target sequence number, and
  * optional cancellation signal.
@@ -81,7 +82,7 @@ export async function loadContainerToSequenceNumber(
 	const capableFactory = asPointInTimeCapableFactory(documentServiceFactory);
 	if (capableFactory === undefined) {
 		throw new UsageError(
-			"The provided documentServiceFactory does not support point-in-time loading. For ODSP, pass the result of getOdspPointInTimeDocumentServiceFactory.",
+			"The provided documentServiceFactory does not support point-in-time loading. For ODSP, call createOdspDocumentServiceFactory with a point-in-time implementation.",
 		);
 	}
 

package/src/packageVersion.ts

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

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