@fluidframework/odsp-driver 2.112.0 → 2.113.1

package/lib/pointInTimeDriver/odspPointInTimeDocumentServiceFactory.d.ts

@@ -0,0 +1,49 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
+import type { IDocumentService, IPersistedCache, IResolvedUrl } from "@fluidframework/driver-definitions/internal";
+import type { HostStoragePolicy, OdspResourceTokenFetchOptions, TokenFetcher } from "@fluidframework/odsp-driver-definitions/internal";
+import { OdspDocumentServiceFactoryCore } from "../odspDocumentServiceFactoryCore.js";
+/**
+ * ODSP document service factory that additionally supports point-in-time (sequence-number-based)
+ * loading.
+ *
+ * @remarks
+ * This extends {@link OdspDocumentServiceFactoryCore} with the ability to materialize a read-only
+ * document service at a requested Fluid sequence number. The loader detects this capability via the
+ * presence of {@link OdspPointInTimeDocumentServiceFactory.createPointInTimeDocumentService}, so
+ * hosts that want to load a container to a target sequence number must construct this factory
+ * (rather than the legacy `OdspDocumentServiceFactory`) and pass it to the loader.
+ *
+ * @internal
+ */
+export declare class OdspPointInTimeDocumentServiceFactory extends OdspDocumentServiceFactoryCore {
+    /**
+     * The storage token fetcher, captured here because the base class keeps it private.
+     */
+    private readonly getStorageTokenForVersions;
+    constructor(getStorageToken: TokenFetcher<OdspResourceTokenFetchOptions>, getWebsocketToken: TokenFetcher<OdspResourceTokenFetchOptions> | undefined, persistedCache?: IPersistedCache, hostPolicy?: HostStoragePolicy);
+    /**
+     * Creates a document service that reads its snapshot from the closest file version at or before
+     * the target and its deltas from the live document, materializing a requested sequence number
+     * through replay.
+     */
+    createPointInTimeDocumentService(resolvedUrl: IResolvedUrl, targetSequenceNumber: number, logger?: ITelemetryBaseLogger, clientIsSummarizer?: boolean): Promise<IDocumentService>;
+    /**
+     * Builds an IOdspVersionManager for the given file, which enumerates the file's stored
+     * versions and resolves the closest version at or before a target sequence number.
+     *
+     * @remarks
+     * This wires up the plumbing the version manager needs to talk to ODSP: it resolves the URL to
+     * its ODSP parts (site/drive/item), creates a scoped child logger, an epoch tracker (from a fresh
+     * NonPersistentCache, since only the tracker is needed for consistency checks), and an
+     * instrumented storage-token/auth-header fetcher. The resulting manager is used by
+     * {@link OdspPointInTimeDocumentServiceFactory.createPointInTimeDocumentService} to pick the base
+     * snapshot for point-in-time loading.
+     */
+    private createVersionManager;
+    private resolveFileVersion;
+}
+//# sourceMappingURL=odspPointInTimeDocumentServiceFactory.d.ts.map

package/lib/pointInTimeDriver/odspPointInTimeDocumentServiceFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odspPointInTimeDocumentServiceFactory.d.ts","sourceRoot":"","sources":["../../src/pointInTimeDriver/odspPointInTimeDocumentServiceFactory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAC5E,OAAO,KAAK,EACX,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,MAAM,6CAA6C,CAAC;AACrD,OAAO,KAAK,EACX,iBAAiB,EAEjB,6BAA6B,EAC7B,YAAY,EACZ,MAAM,kDAAkD,CAAC;AAK1D,OAAO,EAAE,8BAA8B,EAAE,MAAM,sCAAsC,CAAC;AActF;;;;;;;;;;;;GAYG;AACH,qBAAa,qCAAsC,SAAQ,8BAA8B;IACxF;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAA8C;gBAGxF,eAAe,EAAE,YAAY,CAAC,6BAA6B,CAAC,EAC5D,iBAAiB,EAAE,YAAY,CAAC,6BAA6B,CAAC,GAAG,SAAS,EAC1E,cAAc,CAAC,EAAE,eAAe,EAChC,UAAU,CAAC,EAAE,iBAAiB;IAM/B;;;;OAIG;IACU,gCAAgC,CAC5C,WAAW,EAAE,YAAY,EACzB,oBAAoB,EAAE,MAAM,EAC5B,MAAM,CAAC,EAAE,oBAAoB,EAC7B,kBAAkB,CAAC,EAAE,OAAO,GAC1B,OAAO,CAAC,gBAAgB,CAAC;IAuC5B;;;;;;;;;;;OAWG;YACW,oBAAoB;YAuCpB,kBAAkB;CAoBhC"}

package/lib/pointInTimeDriver/odspPointInTimeDocumentServiceFactory.js

@@ -0,0 +1,104 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { UsageError, createChildLogger } from "@fluidframework/telemetry-utils/internal";
+import { createOdspCacheAndTracker } from "../epochTracker.js";
+import { NonPersistentCache } from "../odspCache.js";
+import { OdspDocumentServiceFactoryCore } from "../odspDocumentServiceFactoryCore.js";
+import { OdspDriverUrlResolver } from "../odspDriverUrlResolver.js";
+import { createOdspLogger, getOdspResolvedUrl, toInstrumentedOdspStorageTokenFetcher, } from "../odspUtils.js";
+import { createOdspVersionManager, } from "../odspVersionManager/index.js";
+import { OdspPointInTimeDocumentService } from "./odspPointInTimeDocumentService.js";
+/**
+ * ODSP document service factory that additionally supports point-in-time (sequence-number-based)
+ * loading.
+ *
+ * @remarks
+ * This extends {@link OdspDocumentServiceFactoryCore} with the ability to materialize a read-only
+ * document service at a requested Fluid sequence number. The loader detects this capability via the
+ * presence of {@link OdspPointInTimeDocumentServiceFactory.createPointInTimeDocumentService}, so
+ * hosts that want to load a container to a target sequence number must construct this factory
+ * (rather than the legacy `OdspDocumentServiceFactory`) and pass it to the loader.
+ *
+ * @internal
+ */
+export class OdspPointInTimeDocumentServiceFactory extends OdspDocumentServiceFactoryCore {
+    constructor(getStorageToken, getWebsocketToken, persistedCache, hostPolicy) {
+        super(getStorageToken, getWebsocketToken, persistedCache, hostPolicy);
+        this.getStorageTokenForVersions = getStorageToken;
+    }
+    /**
+     * Creates a document service that reads its snapshot from the closest file version at or before
+     * the target and its deltas from the live document, materializing a requested sequence number
+     * through replay.
+     */
+    async createPointInTimeDocumentService(resolvedUrl, targetSequenceNumber, logger, clientIsSummarizer) {
+        const versionManager = await this.createVersionManager(resolvedUrl, logger, clientIsSummarizer);
+        const baseResult = await versionManager.findBaseForSeq(targetSequenceNumber);
+        if (baseResult.kind === "noBaseVersion") {
+            const oldestResolvedSequenceDetail = baseResult.oldestResolvedSeq === undefined
+                ? ""
+                : ` The oldest resolved file version is at sequence number ${baseResult.oldestResolvedSeq}.`;
+            throw new UsageError(`No ODSP file version is available at or before sequence number ${targetSequenceNumber}.${oldestResolvedSequenceDetail}`);
+        }
+        const recoverableResolvedUrl = await this.resolveFileVersion(resolvedUrl, baseResult.base.versionId);
+        const recoverableDocumentService = await this.createDocumentService(recoverableResolvedUrl, logger, clientIsSummarizer);
+        const liveDocumentService = await this.createDocumentService(resolvedUrl, logger, clientIsSummarizer);
+        return new OdspPointInTimeDocumentService(recoverableResolvedUrl, recoverableDocumentService, liveDocumentService, targetSequenceNumber);
+    }
+    /**
+     * Builds an IOdspVersionManager for the given file, which enumerates the file's stored
+     * versions and resolves the closest version at or before a target sequence number.
+     *
+     * @remarks
+     * This wires up the plumbing the version manager needs to talk to ODSP: it resolves the URL to
+     * its ODSP parts (site/drive/item), creates a scoped child logger, an epoch tracker (from a fresh
+     * NonPersistentCache, since only the tracker is needed for consistency checks), and an
+     * instrumented storage-token/auth-header fetcher. The resulting manager is used by
+     * {@link OdspPointInTimeDocumentServiceFactory.createPointInTimeDocumentService} to pick the base
+     * snapshot for point-in-time loading.
+     */
+    async createVersionManager(resolvedUrl, logger, clientIsSummarizer) {
+        const odspLogger = createOdspLogger(logger);
+        const extLogger = createChildLogger({ logger: odspLogger });
+        const odspResolvedUrl = getOdspResolvedUrl(resolvedUrl);
+        const urlParts = {
+            siteUrl: odspResolvedUrl.siteUrl,
+            driveId: odspResolvedUrl.driveId,
+            itemId: odspResolvedUrl.itemId,
+        };
+        // Only the epochTracker from the returned cacheAndTracker is used below, so a fresh
+        // NonPersistentCache is sufficient here.
+        const cacheAndTracker = createOdspCacheAndTracker(this.persistedCache, new NonPersistentCache(), {
+            resolvedUrl: odspResolvedUrl,
+            docId: odspResolvedUrl.hashedDocumentId,
+            fileVersion: odspResolvedUrl.fileVersion,
+        }, extLogger, clientIsSummarizer);
+        const getAuthHeader = toInstrumentedOdspStorageTokenFetcher(extLogger, urlParts, this.getStorageTokenForVersions);
+        return createOdspVersionManager({
+            urlParts,
+            getAuthHeader,
+            epochTracker: cacheAndTracker.epochTracker,
+            logger: extLogger,
+        });
+    }
+    async resolveFileVersion(resolvedUrl, fileVersion) {
+        const odspResolvedUrl = getOdspResolvedUrl(resolvedUrl);
+        const query = new URLSearchParams({
+            driveId: odspResolvedUrl.driveId,
+            itemId: odspResolvedUrl.itemId,
+            fileVersion,
+        });
+        if (odspResolvedUrl.dataStorePath !== undefined) {
+            query.set("path", odspResolvedUrl.dataStorePath);
+        }
+        if (odspResolvedUrl.codeHint?.containerPackageName !== undefined) {
+            query.set("containerPackageName", odspResolvedUrl.codeHint.containerPackageName);
+        }
+        return new OdspDriverUrlResolver().resolve({
+            url: `${odspResolvedUrl.siteUrl}?${query.toString()}`,
+        });
+    }
+}
+//# sourceMappingURL=odspPointInTimeDocumentServiceFactory.js.map

package/lib/pointInTimeDriver/odspPointInTimeDocumentServiceFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"odspPointInTimeDocumentServiceFactory.js","sourceRoot":"","sources":["../../src/pointInTimeDriver/odspPointInTimeDocumentServiceFactory.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ITelemetryBaseLogger } from \"@fluidframework/core-interfaces\";\nimport type {\n\tIDocumentService,\n\tIPersistedCache,\n\tIResolvedUrl,\n} from \"@fluidframework/driver-definitions/internal\";\nimport type {\n\tHostStoragePolicy,\n\tIOdspUrlParts,\n\tOdspResourceTokenFetchOptions,\n\tTokenFetcher,\n} from \"@fluidframework/odsp-driver-definitions/internal\";\nimport { UsageError, createChildLogger } from \"@fluidframework/telemetry-utils/internal\";\n\nimport { createOdspCacheAndTracker } from \"../epochTracker.js\";\nimport { NonPersistentCache } from \"../odspCache.js\";\nimport { OdspDocumentServiceFactoryCore } from \"../odspDocumentServiceFactoryCore.js\";\nimport { OdspDriverUrlResolver } from \"../odspDriverUrlResolver.js\";\nimport {\n\tcreateOdspLogger,\n\tgetOdspResolvedUrl,\n\ttoInstrumentedOdspStorageTokenFetcher,\n} from \"../odspUtils.js\";\nimport {\n\tcreateOdspVersionManager,\n\ttype IOdspVersionManager,\n} from \"../odspVersionManager/index.js\";\n\nimport { OdspPointInTimeDocumentService } from \"./odspPointInTimeDocumentService.js\";\n\n/**\n * ODSP document service factory that additionally supports point-in-time (sequence-number-based)\n * loading.\n *\n * @remarks\n * This extends {@link OdspDocumentServiceFactoryCore} with the ability to materialize a read-only\n * document service at a requested Fluid sequence number. The loader detects this capability via the\n * presence of {@link OdspPointInTimeDocumentServiceFactory.createPointInTimeDocumentService}, so\n * hosts that want to load a container to a target sequence number must construct this factory\n * (rather than the legacy `OdspDocumentServiceFactory`) and pass it to the loader.\n *\n * @internal\n */\nexport class OdspPointInTimeDocumentServiceFactory extends OdspDocumentServiceFactoryCore {\n\t/**\n\t * The storage token fetcher, captured here because the base class keeps it private.\n\t */\n\tprivate readonly getStorageTokenForVersions: TokenFetcher<OdspResourceTokenFetchOptions>;\n\n\tconstructor(\n\t\tgetStorageToken: TokenFetcher<OdspResourceTokenFetchOptions>,\n\t\tgetWebsocketToken: TokenFetcher<OdspResourceTokenFetchOptions> | undefined,\n\t\tpersistedCache?: IPersistedCache,\n\t\thostPolicy?: HostStoragePolicy,\n\t) {\n\t\tsuper(getStorageToken, getWebsocketToken, persistedCache, hostPolicy);\n\t\tthis.getStorageTokenForVersions = getStorageToken;\n\t}\n\n\t/**\n\t * Creates a document service that reads its snapshot from the closest file version at or before\n\t * the target and its deltas from the live document, materializing a requested sequence number\n\t * through replay.\n\t */\n\tpublic async createPointInTimeDocumentService(\n\t\tresolvedUrl: IResolvedUrl,\n\t\ttargetSequenceNumber: number,\n\t\tlogger?: ITelemetryBaseLogger,\n\t\tclientIsSummarizer?: boolean,\n\t): Promise<IDocumentService> {\n\t\tconst versionManager = await this.createVersionManager(\n\t\t\tresolvedUrl,\n\t\t\tlogger,\n\t\t\tclientIsSummarizer,\n\t\t);\n\t\tconst baseResult = await versionManager.findBaseForSeq(targetSequenceNumber);\n\t\tif (baseResult.kind === \"noBaseVersion\") {\n\t\t\tconst oldestResolvedSequenceDetail =\n\t\t\t\tbaseResult.oldestResolvedSeq === undefined\n\t\t\t\t\t? \"\"\n\t\t\t\t\t: ` The oldest resolved file version is at sequence number ${baseResult.oldestResolvedSeq}.`;\n\t\t\tthrow new UsageError(\n\t\t\t\t`No ODSP file version is available at or before sequence number ${targetSequenceNumber}.${oldestResolvedSequenceDetail}`,\n\t\t\t);\n\t\t}\n\n\t\tconst recoverableResolvedUrl = await this.resolveFileVersion(\n\t\t\tresolvedUrl,\n\t\t\tbaseResult.base.versionId,\n\t\t);\n\t\tconst recoverableDocumentService = await this.createDocumentService(\n\t\t\trecoverableResolvedUrl,\n\t\t\tlogger,\n\t\t\tclientIsSummarizer,\n\t\t);\n\t\tconst liveDocumentService = await this.createDocumentService(\n\t\t\tresolvedUrl,\n\t\t\tlogger,\n\t\t\tclientIsSummarizer,\n\t\t);\n\t\treturn new OdspPointInTimeDocumentService(\n\t\t\trecoverableResolvedUrl,\n\t\t\trecoverableDocumentService,\n\t\t\tliveDocumentService,\n\t\t\ttargetSequenceNumber,\n\t\t);\n\t}\n\n\t/**\n\t * Builds an IOdspVersionManager for the given file, which enumerates the file's stored\n\t * versions and resolves the closest version at or before a target sequence number.\n\t *\n\t * @remarks\n\t * This wires up the plumbing the version manager needs to talk to ODSP: it resolves the URL to\n\t * its ODSP parts (site/drive/item), creates a scoped child logger, an epoch tracker (from a fresh\n\t * NonPersistentCache, since only the tracker is needed for consistency checks), and an\n\t * instrumented storage-token/auth-header fetcher. The resulting manager is used by\n\t * {@link OdspPointInTimeDocumentServiceFactory.createPointInTimeDocumentService} to pick the base\n\t * snapshot for point-in-time loading.\n\t */\n\tprivate async createVersionManager(\n\t\tresolvedUrl: IResolvedUrl,\n\t\tlogger?: ITelemetryBaseLogger,\n\t\tclientIsSummarizer?: boolean,\n\t): Promise<IOdspVersionManager> {\n\t\tconst odspLogger = createOdspLogger(logger);\n\t\tconst extLogger = createChildLogger({ logger: odspLogger });\n\t\tconst odspResolvedUrl = getOdspResolvedUrl(resolvedUrl);\n\t\tconst urlParts: IOdspUrlParts = {\n\t\t\tsiteUrl: odspResolvedUrl.siteUrl,\n\t\t\tdriveId: odspResolvedUrl.driveId,\n\t\t\titemId: odspResolvedUrl.itemId,\n\t\t};\n\t\t// Only the epochTracker from the returned cacheAndTracker is used below, so a fresh\n\t\t// NonPersistentCache is sufficient here.\n\t\tconst cacheAndTracker = createOdspCacheAndTracker(\n\t\t\tthis.persistedCache,\n\t\t\tnew NonPersistentCache(),\n\t\t\t{\n\t\t\t\tresolvedUrl: odspResolvedUrl,\n\t\t\t\tdocId: odspResolvedUrl.hashedDocumentId,\n\t\t\t\tfileVersion: odspResolvedUrl.fileVersion,\n\t\t\t},\n\t\t\textLogger,\n\t\t\tclientIsSummarizer,\n\t\t);\n\t\tconst getAuthHeader = toInstrumentedOdspStorageTokenFetcher(\n\t\t\textLogger,\n\t\t\turlParts,\n\t\t\tthis.getStorageTokenForVersions,\n\t\t);\n\t\treturn createOdspVersionManager({\n\t\t\turlParts,\n\t\t\tgetAuthHeader,\n\t\t\tepochTracker: cacheAndTracker.epochTracker,\n\t\t\tlogger: extLogger,\n\t\t});\n\t}\n\n\tprivate async resolveFileVersion(\n\t\tresolvedUrl: IResolvedUrl,\n\t\tfileVersion: string,\n\t): Promise<IResolvedUrl> {\n\t\tconst odspResolvedUrl = getOdspResolvedUrl(resolvedUrl);\n\t\tconst query = new URLSearchParams({\n\t\t\tdriveId: odspResolvedUrl.driveId,\n\t\t\titemId: odspResolvedUrl.itemId,\n\t\t\tfileVersion,\n\t\t});\n\t\tif (odspResolvedUrl.dataStorePath !== undefined) {\n\t\t\tquery.set(\"path\", odspResolvedUrl.dataStorePath);\n\t\t}\n\t\tif (odspResolvedUrl.codeHint?.containerPackageName !== undefined) {\n\t\t\tquery.set(\"containerPackageName\", odspResolvedUrl.codeHint.containerPackageName);\n\t\t}\n\t\treturn new OdspDriverUrlResolver().resolve({\n\t\t\turl: `${odspResolvedUrl.siteUrl}?${query.toString()}`,\n\t\t});\n\t}\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/odsp-driver",
-  "version": "2.112.0",
+  "version": "2.113.1",
   "description": "Socket storage implementation for SPO and ODC",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -69,22 +69,22 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.112.0",
-    "@fluidframework/core-interfaces": "~2.112.0",
-    "@fluidframework/core-utils": "~2.112.0",
-    "@fluidframework/driver-base": "~2.112.0",
-    "@fluidframework/driver-definitions": "~2.112.0",
-    "@fluidframework/driver-utils": "~2.112.0",
-    "@fluidframework/odsp-doclib-utils": "~2.112.0",
-    "@fluidframework/odsp-driver-definitions": "~2.112.0",
-    "@fluidframework/telemetry-utils": "~2.112.0",
+    "@fluid-internal/client-utils": "~2.113.1",
+    "@fluidframework/core-interfaces": "~2.113.1",
+    "@fluidframework/core-utils": "~2.113.1",
+    "@fluidframework/driver-base": "~2.113.1",
+    "@fluidframework/driver-definitions": "~2.113.1",
+    "@fluidframework/driver-utils": "~2.113.1",
+    "@fluidframework/odsp-doclib-utils": "~2.113.1",
+    "@fluidframework/odsp-driver-definitions": "~2.113.1",
+    "@fluidframework/telemetry-utils": "~2.113.1",
     "socket.io-client": "^4.8.3",
     "uuid": "^11.1.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-internal/mocha-test-setup": "~2.112.0",
+    "@fluid-internal/mocha-test-setup": "~2.113.1",
     "@fluid-tools/build-cli": "^0.65.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.65.0",

package/src/index.ts

@@ -29,6 +29,8 @@ export {
 	OdspDocumentServiceFactory,
 } from "./odspDocumentServiceFactory.js";
 export { OdspDocumentServiceFactoryCore } from "./odspDocumentServiceFactoryCore.js";
+// eslint-disable-next-line import-x/no-internal-modules
+export { OdspPointInTimeDocumentServiceFactory } from "./pointInTimeDriver/odspPointInTimeDocumentServiceFactory.js";
 
 // File creation
 export { createOdspCreateContainerRequest } from "./createOdspCreateContainerRequest.js";

package/src/odspVersionManager/DEV.md

@@ -35,8 +35,11 @@ Part 1 is built in three components:
 - **Component A — the version manager**: choose which file version to load or replay from. **This
   folder is Component A**, and this document is mostly about it.
 - **Component B — the recomposed driver**: load the chosen version and replay ops forward to the exact
-  target. Not built yet.
-- **Component C — the loader hookup**: expose Component B through the container loader. Not built yet.
+  target. **Built** in `../pointInTimeDriver/` (`OdspPointInTimeDocumentServiceFactory` /
+  `OdspPointInTimeDocumentService`) — see [Part V](#part-v--components-b--c-as-built).
+- **Component C — the loader hookup**: expose Component B through the container loader. **Built** in
+  `@fluidframework/container-loader` (`loadContainerToSequenceNumber`) — see
+  [Part V](#part-v--components-b--c-as-built).
 
 ## Part I — Foundations
 
@@ -79,10 +82,13 @@ driver's normal (`application/json` or `application/ms-fluid`) framing. The driv
 parser reads it, and the sequence number is `trees[0].sequenceNumber`. `blobs=2` inlines blob contents
 so the parser has everything it needs.
 
-### What is deliberately not built here?
+### What is deliberately not built in *this folder*?
 
-Loading the base and replaying ops to the exact target (Component B), the loader hookup (Component C),
-and any test against a live ODSP file. See [Part IV](#part-iv--directional).
+Components B and C now exist, but elsewhere: the recomposed driver in `../pointInTimeDriver/` and the
+loader hookup in `@fluidframework/container-loader` (see
+[Part V](#part-v--components-b--c-as-built)). This folder (Component A) still owns only base selection.
+Not built anywhere yet: bridging a trimmed op range via an intermediate snapshot, and a test against a
+live ODSP file. See [Part IV](#part-iv--directional).
 
 ## Part II — The Version Manager
 
@@ -215,25 +221,13 @@ comparison. It also allows locating a version by time when no sequence number is
 
 
 
-### Should there be a component that loads the base and replays ops to the exact target? (Component B)
+### How would Component B bridge a *trimmed* op range between snapshots?
 
-The manager only chooses the base. Materializing the document at an arbitrary target requires loading
-that version read-only and replaying the ops between the base and the target — sourcing later ops from
-the live op stream when the historical range has been trimmed.
-
-Where would it live? In **this package**. Loading a historical file version is a storage-layer concern:
-it needs the version-scoped snapshot fetch, the epoch tracker, and authentication — all internal to this
-driver — and it consumes the version manager directly. A generic wrapping driver that only replays ops
-over an inner document service (the pattern `@fluidframework/replay-driver` uses) cannot reach the
-version-scoped base fetch, so the recomposition belongs beside `OdspDocumentService` /
-`OdspDocumentServiceFactory` rather than in a separate package. Because it consumes the version manager
-in-package, the version manager itself needs no exported surface; only the recomposed factory is exposed
-(defaulting to an internal entry point) for the loader hookup to construct.
-
-A base is only needed when the live document's own snapshot no longer covers the target; when it does,
-loading paused at the target from the live snapshot suffices, and no historical version is loaded.
-
-### How would Component B reach a target between snapshots, and handle trimmed ops?
+Component B is built (see [Part V](#part-v--components-b--c-as-built)), but the version it ships makes
+one simplifying assumption: it loads a single base file version and replays the ops in `(base, target]`
+from the **live** document's delta storage. That assumption holds only while those ops are still
+retained. Bridging a *trimmed* range by starting from a newer intermediate snapshot is the part that is
+not built yet — the rest of this answer is its design.
 
 A snapshot already contains the full accumulated state at its sequence number — every op at or below it
 is baked in. So to reach a target `T`, Component B loads the closest base snapshot (`seq ≤ T`) and
@@ -259,12 +253,6 @@ baked into a snapshot, used when a snapshot is loaded, not an indicator of which
 retains. Op availability is determined by asking the op stream for the range, not by a version's minimum
 sequence number.
 
-### Should this be exposed through the container loader? (Component C)
-
-Once Component B exists, a thin combining layer would construct the recomposed factory together with a
-standard loader, letting callers request "load at sequence number N" directly. It depends only on
-Component B's exposed factory, never on the version manager.
-
 ### Should there be an end-to-end test against a real ODSP file?
 
 The fetcher is covered by stubbed-`fetch` integration tests, but not against a live file (which needs
@@ -275,3 +263,87 @@ tenant credentials). An end-to-end test would exercise the real endpoints.
 The `/content` download also contains a version's snapshot, but wrapped in a container framing the
 snapshot parser does not read directly. If the version-scoped snapshot endpoint is ever unavailable,
 unwrapping `/content` could be a fallback path.
+
+## Part V — Components B & C, as built
+
+Component A (this folder) only selects the base. Components B and C — which materialize the document at
+the target and expose it through the loader — are now built, in other files. They carry no catechism
+code IDs here because their are no tests at the moment; these are
+conceptual answers in the spirit of [Part I](#part-i--foundations). The one still-directional gap is
+bridging a *trimmed* op range via an intermediate snapshot (see
+[Part IV](#part-iv--directional)); everything below is what ships today.
+
+### Component B — how does the recomposed driver materialize the target?
+
+`OdspPointInTimeDocumentServiceFactory` (in `../pointInTimeDriver/`) extends
+`OdspDocumentServiceFactoryCore` and adds `createPointInTimeDocumentService(resolvedUrl, targetSequenceNumber)`:
+
+1. Build a version manager (Component A) and call `findBaseForSeq(target)`. A `noBaseVersion` result
+   becomes a `UsageError` naming the target and the oldest resolved sequence number.
+2. Resolve the chosen file version into a version-scoped resolved URL, then create two ordinary ODSP
+   document services: a **recoverable** one bound to that base version (its storage is the base
+   snapshot) and a **live** one (its delta storage supplies the ops to replay).
+3. Return an `OdspPointInTimeDocumentService` composing the two.
+
+It lives in this package rather than a generic wrapping driver (e.g. `@fluidframework/replay-driver`)
+because loading a historical file version is a storage-layer concern: it needs the version-scoped
+snapshot fetch, the epoch tracker, and authentication — all internal to this driver — and it consumes
+the version manager in-package, so the manager itself needs no exported surface.
+
+### Component B — which `IDocumentService` method drives the replay?
+
+`OdspPointInTimeDocumentService` is read-only and advertises the `storageOnly` document-service policy.
+Its three `IDocumentService` methods:
+
+- `connectToStorage` → the recoverable (base-version) service's storage: the base snapshot.
+- `connectToDeltaStorage` → wraps the **live** service's delta storage and clamps every
+  **`fetchMessages(from, to, …)`** call to an exclusive upper bound of `targetSequenceNumber + 1`, so no
+  op past the target is ever fetched. **`fetchMessages` is the method that drives the bounded replay.**
+- `connectToDeltaStream` → throws: under `storageOnly` the connection manager synthesizes a frozen,
+  read-only delta stream instead of opening a live socket, so this is never called under normal flow.
+
+The `storageOnly` policy is the key mechanism: it forces the container read-only and reuses the loader's
+existing "frozen" delta stream, and the delta manager then catches up from the base snapshot's sequence
+number through delta storage — the bounded `fetchMessages` replay — up to and including the target op.
+
+### Component B — what request does the bounded `fetchMessages` actually make?
+
+The point-in-time service builds no URL of its own: `connectToDeltaStorage` wraps the **live** service's
+delta storage and only clamps the `to` argument (`Math.min(to, targetSequenceNumber + 1)`). Everything
+below is the ordinary ODSP delta path (`OdspDeltaStorageWithCache` → `OdspDeltaStorageService`), just
+range-constrained by that clamp.
+
+`OdspDeltaStorageWithCache.fetchMessages` is a **paged stream**, not a single request: via `requestOps`
+it walks the requested `[from, to)` in batches, checking three sources in order — ops bundled with the
+base snapshot, then the cache, then network storage — so the clamp guarantees no page is ever requested
+past the target.
+
+The network leg (`OdspDeltaStorageService.get`) is where the request is constructed:
+
+- **URL** (`buildUrl`): `${deltaStorageUrl}?ump=1&filter=` + `encodeURIComponent("sequenceNumber ge {from} and sequenceNumber le {to - 1}")`.
+  `deltaStorageUrl` is `.../drives/{driveId}/items/{itemId}/opStream`. Because `from` is inclusive and
+  `to` exclusive, the filter is `ge {from} and le {to - 1}`; with the clamped `to = target + 1` the
+  effective server bound is `sequenceNumber le target` — the target op is included, nothing beyond it.
+- **Method & body**: despite fetching ops it issues a **`POST`** carrying `X-HTTP-Method-Override: GET`,
+  encoded as `multipart/form-data` (the `ump=1` "unified multipart" framing). The auth token rides in the
+  form body (`Authorization: {authHeader}` / `_post: 1`), not a header.
+- **Plumbing**: the call goes through the `epochTracker` (epoch/consistency checks) and
+  `getWithRetryForTokenRefresh` (one token-refresh retry), with a 30s `AbortController` timeout as a
+  hang mitigation.
+
+So the target bound flows `target + 1` → `Math.min` clamp → stream page `to` → `le {to - 1}` filter,
+and the `opStream` endpoint is queried for exactly `[from, target]`.
+
+### Component C — how is this exposed through the loader?
+
+`loadContainerToSequenceNumber` (in `@fluidframework/container-loader`):
+
+1. Validates `loadToSequenceNumber` is a non-negative integer (`UsageError` otherwise).
+2. Detects the point-in-time capability with `asPointInTimeCapableFactory`, which checks the passed
+   `documentServiceFactory` exposes `createPointInTimeDocumentService`. A plain factory is a
+   `UsageError` — the caller must pass `OdspPointInTimeDocumentServiceFactory` directly, with no wrapping.
+3. Wraps it in a `PointInTimeDocumentServiceFactory` adapter so the container's normal
+   `createDocumentService(resolvedUrl)` routes to `createPointInTimeDocumentService(resolvedUrl, target)`.
+   (`createContainer` throws — the adapter is load-only.)
+4. Delegates to `loadContainerPaused(...)` with inbound/outbound processing paused, returning a
+   disconnected, read-only historical view of the container at the target sequence number.

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/odsp-driver";
-export const pkgVersion = "2.112.0";
+export const pkgVersion = "2.113.1";

package/src/pointInTimeDriver/odspPointInTimeDocumentService.ts

@@ -0,0 +1,94 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
+import type {
+	IClient,
+	IDocumentDeltaConnection,
+	IDocumentDeltaStorageService,
+	IDocumentService,
+	IDocumentServiceEvents,
+	IDocumentServicePolicies,
+	IDocumentStorageService,
+	IResolvedUrl,
+} from "@fluidframework/driver-definitions/internal";
+
+/**
+ * A read-only document service that materializes a document at a target sequence number by combining
+ * a recoverable snapshot with a bounded replay of live ops.
+ *
+ * @remarks
+ * Storage (the snapshot) is served from the closest file version at or before the target sequence
+ * number. The ops needed to advance from that snapshot to the target are read from the live
+ * document's delta storage, bounded so that no op past the target is ever fetched.
+ *
+ * The service advertises the {@link IDocumentServicePolicies.storageOnly} policy. This reuses the
+ * loader's "frozen" load mechanism: the connection manager synthesizes a read-only frozen delta
+ * stream instead of opening a live socket, and forces the container read-only. The delta manager
+ * still catches up from the snapshot's sequence number through delta storage, which is exactly the
+ * bounded replay we want. As a result no live delta-stream connection is ever established.
+ *
+ * @internal
+ */
+export class OdspPointInTimeDocumentService
+	extends TypedEventEmitter<IDocumentServiceEvents>
+	implements IDocumentService
+{
+	public constructor(
+		public readonly resolvedUrl: IResolvedUrl,
+		// Serves the snapshot: a read-only document service bound to the closest file version at or
+		// before the target sequence number. Its storage is the base we replay ops on top of.
+		private readonly recoverableDocumentService: IDocumentService,
+		private readonly liveDocumentService: IDocumentService,
+		private readonly targetSequenceNumber: number,
+	) {
+		super();
+		this.liveDocumentService.on("metadataUpdate", this.metadataUpdateHandler);
+	}
+
+	// storageOnly makes the connection manager synthesize a read-only frozen delta stream (no live
+	// socket) and force the container read-only - see the class remarks.
+	public readonly policies: IDocumentServicePolicies = { storageOnly: true };
+
+	public dispose(): void {
+		this.liveDocumentService.off("metadataUpdate", this.metadataUpdateHandler);
+		this.recoverableDocumentService.dispose();
+		this.liveDocumentService.dispose();
+	}
+
+	public async connectToStorage(): Promise<IDocumentStorageService> {
+		return this.recoverableDocumentService.connectToStorage();
+	}
+
+	public async connectToDeltaStorage(): Promise<IDocumentDeltaStorageService> {
+		const liveDeltaStorage = await this.liveDocumentService.connectToDeltaStorage();
+		// The exclusive upper bound needed to include the target op itself.
+		const boundedTo = this.targetSequenceNumber + 1;
+		return {
+			fetchMessages: (from, to, abortSignal, cachedOnly, fetchReason) => {
+				return liveDeltaStorage.fetchMessages(
+					from,
+					to === undefined ? boundedTo : Math.min(to, boundedTo),
+					abortSignal,
+					cachedOnly,
+					fetchReason,
+				);
+			},
+		};
+	}
+
+	public async connectToDeltaStream(_client: IClient): Promise<IDocumentDeltaConnection> {
+		// Unreachable under normal flow: the connection manager short-circuits on the storageOnly
+		// policy and synthesizes a frozen delta stream before ever calling connectToDeltaStream.
+		// Reaching here indicates a regression of that short-circuit.
+		throw new Error(
+			"OdspPointInTimeDocumentService is storage-only; connectToDeltaStream should not be called",
+		);
+	}
+
+	private readonly metadataUpdateHandler = (metadata: Record<string, string>): void => {
+		this.emit("metadataUpdate", metadata);
+	};
+}