@fluidframework/odsp-driver 2.111.0 → 2.112.0

package/lib/odspVersionManager/odspVersionManager.d.ts

@@ -0,0 +1,98 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Selects the ODSP file version whose snapshot sits at or before a target Fluid sequence number —
+ * the base to load or replay from when materializing a document at a point in time.
+ *
+ * The selection logic depends on an injected {@link IOdspFileVersionFetcher}, so it is independent of
+ * how versions are enumerated and resolved (real ODSP, a test double, or an alternative backend).
+ */
+import { type OdspFileVersionFetcherProps } from "./odspFileVersionFetcher.js";
+/**
+ * A single ODSP file version, as listed by the file's version history.
+ */
+export interface OdspFileVersionRef {
+    /**
+     * The version's label (e.g. `"42.0"`), used to address the version when fetching it.
+     */
+    readonly versionId: string;
+    /**
+     * Last-modified timestamp of this version, ISO-8601.
+     */
+    readonly lastModifiedDateTime: string;
+}
+/**
+ * An ODSP file version together with its resolved Fluid sequence number.
+ */
+export interface ResolvedVersion extends OdspFileVersionRef {
+    /**
+     * The Fluid sequence number the version's snapshot represents.
+     */
+    readonly sequenceNumber: number;
+}
+/**
+ * Result of resolving the base version for a target sequence number.
+ *
+ * @remarks
+ * There is intentionally no `targetIsLive` case: when the target is at/after the newest recoverable
+ * version, the greatest version with `seq <= target` IS that newest version, so it is a normal
+ * `found`. A consumer may separately choose to load the live file when the target is near the head.
+ */
+export type BaseForSeq = {
+    /** A recoverable version with `sequenceNumber <= target` was found. */
+    readonly kind: "found";
+    readonly base: ResolvedVersion;
+} | {
+    /** No recoverable version has `sequenceNumber <= target` (target predates retained history). */
+    readonly kind: "noBaseVersion";
+    /** The oldest sequence number that was resolved while searching, if any. */
+    readonly oldestResolvedSeq?: number;
+};
+/**
+ * Provides a file's versions and resolves each version's Fluid sequence number. Injected into
+ * the version manager so the selection logic does not depend on how versions are fetched.
+ */
+export interface IOdspFileVersionFetcher {
+    /**
+     * Enumerate the file's versions, newest-first.
+     */
+    listFileVersions(): Promise<OdspFileVersionRef[]>;
+    /**
+     * Resolve a single version's Fluid sequence number. Throws on failure rather than returning a
+     * wrong value.
+     */
+    resolveSequenceNumber(versionId: string): Promise<number>;
+}
+/**
+ * Selects the file version to use as the base for loading or replaying to a target sequence number.
+ */
+export interface IOdspVersionManager {
+    /**
+     * Given a target sequence number, return the closest version at or before it (`found`), or
+     * `noBaseVersion` if the target predates the oldest retained version.
+     */
+    findBaseForSeq(target: number): Promise<BaseForSeq>;
+}
+/**
+ * Default {@link IOdspVersionManager}. Caches the version list and resolved sequence numbers. The
+ * resolution strategy (eager, newest-to-oldest, stopping at the first usable base) is hidden behind
+ * {@link findBaseForSeq} and can change without affecting callers.
+ */
+export declare class OdspVersionManager implements IOdspVersionManager {
+    private readonly fetcher;
+    private versionsCache;
+    private readonly seqByVersion;
+    constructor(fetcher: IOdspFileVersionFetcher);
+    refresh(): void;
+    findBaseForSeq(target: number): Promise<BaseForSeq>;
+    listVersions(): Promise<ResolvedVersion[]>;
+    private getVersions;
+    private resolveSeq;
+}
+/**
+ * Create an {@link IOdspVersionManager} for a specific ODSP file, wired to the real ODSP REST APIs.
+ */
+export declare function createOdspVersionManager(props: OdspFileVersionFetcherProps): IOdspVersionManager;
+//# sourceMappingURL=odspVersionManager.d.ts.map

package/lib/odspVersionManager/odspVersionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odspVersionManager.d.ts","sourceRoot":"","sources":["../../src/odspVersionManager/odspVersionManager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,EAEN,KAAK,2BAA2B,EAChC,MAAM,6BAA6B,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IAC1D;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GACnB;IACA,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;CAC9B,GACD;IACA,gGAAgG;IAChG,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACnC,CAAC;AAEL;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACvC;;OAEG;IACH,gBAAgB,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAClD;;;OAGG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACpD;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAI1C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH3C,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;gBAE/B,OAAO,EAAE,uBAAuB;IAE7D,OAAO,IAAI,IAAI;IAKT,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAyBnD,YAAY,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;YAYzC,WAAW;YAOX,UAAU;CAUxB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACvC,KAAK,EAAE,2BAA2B,GAChC,mBAAmB,CAErB"}

package/lib/odspVersionManager/odspVersionManager.js

@@ -0,0 +1,82 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Selects the ODSP file version whose snapshot sits at or before a target Fluid sequence number —
+ * the base to load or replay from when materializing a document at a point in time.
+ *
+ * The selection logic depends on an injected {@link IOdspFileVersionFetcher}, so it is independent of
+ * how versions are enumerated and resolved (real ODSP, a test double, or an alternative backend).
+ */
+import { createOdspFileVersionFetcher, } from "./odspFileVersionFetcher.js";
+/**
+ * Default {@link IOdspVersionManager}. Caches the version list and resolved sequence numbers. The
+ * resolution strategy (eager, newest-to-oldest, stopping at the first usable base) is hidden behind
+ * {@link findBaseForSeq} and can change without affecting callers.
+ */
+export class OdspVersionManager {
+    constructor(fetcher) {
+        this.fetcher = fetcher;
+        this.seqByVersion = new Map();
+    }
+    refresh() {
+        this.versionsCache = undefined;
+        this.seqByVersion.clear();
+    }
+    async findBaseForSeq(target) {
+        // Recoverable base candidates = every version except the tip (index 0 ≈ the live document).
+        const versions = await this.getVersions();
+        const candidates = versions.slice(1);
+        // Versions are listed newest-first, and version order is expected to track sequence number, so
+        // the first candidate whose seq is at or before the target is taken as the closest base. Because
+        // any base at or before the target replays forward to the same state, this early stop is an
+        // optimization, not a correctness requirement: if version order and sequence order ever diverge,
+        // a base that is valid but not strictly the closest may be chosen.
+        // Scanning newest-first also yields the newest of versions sharing a sequence number (dedup).
+        let oldestResolvedSeq;
+        for (const version of candidates) {
+            const sequenceNumber = await this.resolveSeq(version.versionId);
+            oldestResolvedSeq =
+                oldestResolvedSeq === undefined
+                    ? sequenceNumber
+                    : Math.min(oldestResolvedSeq, sequenceNumber);
+            if (sequenceNumber <= target) {
+                return { kind: "found", base: { ...version, sequenceNumber } };
+            }
+        }
+        return { kind: "noBaseVersion", oldestResolvedSeq };
+    }
+    async listVersions() {
+        const versions = await this.getVersions();
+        // Resolution order does not matter here, so resolve concurrently; the newest-first array order is
+        // preserved by Promise.all regardless of completion order.
+        return Promise.all(versions.map(async (version) => ({
+            ...version,
+            sequenceNumber: await this.resolveSeq(version.versionId),
+        })));
+    }
+    async getVersions() {
+        // Cache the pending promise, not the awaited value, so concurrent callers share one fetch and a
+        // refresh() that runs while the fetch is in flight is not overwritten when the fetch settles.
+        this.versionsCache ??= this.fetcher.listFileVersions();
+        return this.versionsCache;
+    }
+    async resolveSeq(versionId) {
+        // Cache the pending promise (a version's sequence number never changes) so concurrent callers
+        // coalesce and a refresh() is not clobbered by a fetch that was already in flight.
+        let pending = this.seqByVersion.get(versionId);
+        if (pending === undefined) {
+            pending = this.fetcher.resolveSequenceNumber(versionId);
+            this.seqByVersion.set(versionId, pending);
+        }
+        return pending;
+    }
+}
+/**
+ * Create an {@link IOdspVersionManager} for a specific ODSP file, wired to the real ODSP REST APIs.
+ */
+export function createOdspVersionManager(props) {
+    return new OdspVersionManager(createOdspFileVersionFetcher(props));
+}
+//# sourceMappingURL=odspVersionManager.js.map

package/lib/odspVersionManager/odspVersionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"odspVersionManager.js","sourceRoot":"","sources":["../../src/odspVersionManager/odspVersionManager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,EACN,4BAA4B,GAE5B,MAAM,6BAA6B,CAAC;AA0ErC;;;;GAIG;AACH,MAAM,OAAO,kBAAkB;IAI9B,YAAoC,OAAgC;QAAhC,YAAO,GAAP,OAAO,CAAyB;QAFnD,iBAAY,GAAG,IAAI,GAAG,EAA2B,CAAC;IAEI,CAAC;IAEjE,OAAO;QACb,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;QAC/B,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAEM,KAAK,CAAC,cAAc,CAAC,MAAc;QACzC,4FAA4F;QAC5F,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1C,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAErC,+FAA+F;QAC/F,iGAAiG;QACjG,4FAA4F;QAC5F,iGAAiG;QACjG,mEAAmE;QACnE,8FAA8F;QAC9F,IAAI,iBAAqC,CAAC;QAC1C,KAAK,MAAM,OAAO,IAAI,UAAU,EAAE,CAAC;YAClC,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAChE,iBAAiB;gBAChB,iBAAiB,KAAK,SAAS;oBAC9B,CAAC,CAAC,cAAc;oBAChB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAAC;YAChD,IAAI,cAAc,IAAI,MAAM,EAAE,CAAC;gBAC9B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,cAAc,EAAE,EAAE,CAAC;YAChE,CAAC;QACF,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,iBAAiB,EAAE,CAAC;IACrD,CAAC;IAEM,KAAK,CAAC,YAAY;QACxB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1C,kGAAkG;QAClG,2DAA2D;QAC3D,OAAO,OAAO,CAAC,GAAG,CACjB,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;YAChC,GAAG,OAAO;YACV,cAAc,EAAE,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC;SACxD,CAAC,CAAC,CACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW;QACxB,gGAAgG;QAChG,8FAA8F;QAC9F,IAAI,CAAC,aAAa,KAAK,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC;QACvD,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;IAEO,KAAK,CAAC,UAAU,CAAC,SAAiB;QACzC,8FAA8F;QAC9F,mFAAmF;QACnF,IAAI,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC;YACxD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;CACD;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACvC,KAAkC;IAElC,OAAO,IAAI,kBAAkB,CAAC,4BAA4B,CAAC,KAAK,CAAC,CAAC,CAAC;AACpE,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Selects the ODSP file version whose snapshot sits at or before a target Fluid sequence number —\n * the base to load or replay from when materializing a document at a point in time.\n *\n * The selection logic depends on an injected {@link IOdspFileVersionFetcher}, so it is independent of\n * how versions are enumerated and resolved (real ODSP, a test double, or an alternative backend).\n */\n\nimport {\n\tcreateOdspFileVersionFetcher,\n\ttype OdspFileVersionFetcherProps,\n} from \"./odspFileVersionFetcher.js\";\n\n/**\n * A single ODSP file version, as listed by the file's version history.\n */\nexport interface OdspFileVersionRef {\n\t/**\n\t * The version's label (e.g. `\"42.0\"`), used to address the version when fetching it.\n\t */\n\treadonly versionId: string;\n\t/**\n\t * Last-modified timestamp of this version, ISO-8601.\n\t */\n\treadonly lastModifiedDateTime: string;\n}\n\n/**\n * An ODSP file version together with its resolved Fluid sequence number.\n */\nexport interface ResolvedVersion extends OdspFileVersionRef {\n\t/**\n\t * The Fluid sequence number the version's snapshot represents.\n\t */\n\treadonly sequenceNumber: number;\n}\n\n/**\n * Result of resolving the base version for a target sequence number.\n *\n * @remarks\n * There is intentionally no `targetIsLive` case: when the target is at/after the newest recoverable\n * version, the greatest version with `seq <= target` IS that newest version, so it is a normal\n * `found`. A consumer may separately choose to load the live file when the target is near the head.\n */\nexport type BaseForSeq =\n\t| {\n\t\t\t/** A recoverable version with `sequenceNumber <= target` was found. */\n\t\t\treadonly kind: \"found\";\n\t\t\treadonly base: ResolvedVersion;\n\t  }\n\t| {\n\t\t\t/** No recoverable version has `sequenceNumber <= target` (target predates retained history). */\n\t\t\treadonly kind: \"noBaseVersion\";\n\t\t\t/** The oldest sequence number that was resolved while searching, if any. */\n\t\t\treadonly oldestResolvedSeq?: number;\n\t  };\n\n/**\n * Provides a file's versions and resolves each version's Fluid sequence number. Injected into\n * the version manager so the selection logic does not depend on how versions are fetched.\n */\nexport interface IOdspFileVersionFetcher {\n\t/**\n\t * Enumerate the file's versions, newest-first.\n\t */\n\tlistFileVersions(): Promise<OdspFileVersionRef[]>;\n\t/**\n\t * Resolve a single version's Fluid sequence number. Throws on failure rather than returning a\n\t * wrong value.\n\t */\n\tresolveSequenceNumber(versionId: string): Promise<number>;\n}\n\n/**\n * Selects the file version to use as the base for loading or replaying to a target sequence number.\n */\nexport interface IOdspVersionManager {\n\t/**\n\t * Given a target sequence number, return the closest version at or before it (`found`), or\n\t * `noBaseVersion` if the target predates the oldest retained version.\n\t */\n\tfindBaseForSeq(target: number): Promise<BaseForSeq>;\n}\n\n/**\n * Default {@link IOdspVersionManager}. Caches the version list and resolved sequence numbers. The\n * resolution strategy (eager, newest-to-oldest, stopping at the first usable base) is hidden behind\n * {@link findBaseForSeq} and can change without affecting callers.\n */\nexport class OdspVersionManager implements IOdspVersionManager {\n\tprivate versionsCache: Promise<OdspFileVersionRef[]> | undefined;\n\tprivate readonly seqByVersion = new Map<string, Promise<number>>();\n\n\tpublic constructor(private readonly fetcher: IOdspFileVersionFetcher) {}\n\n\tpublic refresh(): void {\n\t\tthis.versionsCache = undefined;\n\t\tthis.seqByVersion.clear();\n\t}\n\n\tpublic async findBaseForSeq(target: number): Promise<BaseForSeq> {\n\t\t// Recoverable base candidates = every version except the tip (index 0 ≈ the live document).\n\t\tconst versions = await this.getVersions();\n\t\tconst candidates = versions.slice(1);\n\n\t\t// Versions are listed newest-first, and version order is expected to track sequence number, so\n\t\t// the first candidate whose seq is at or before the target is taken as the closest base. Because\n\t\t// any base at or before the target replays forward to the same state, this early stop is an\n\t\t// optimization, not a correctness requirement: if version order and sequence order ever diverge,\n\t\t// a base that is valid but not strictly the closest may be chosen.\n\t\t// Scanning newest-first also yields the newest of versions sharing a sequence number (dedup).\n\t\tlet oldestResolvedSeq: number | undefined;\n\t\tfor (const version of candidates) {\n\t\t\tconst sequenceNumber = await this.resolveSeq(version.versionId);\n\t\t\toldestResolvedSeq =\n\t\t\t\toldestResolvedSeq === undefined\n\t\t\t\t\t? sequenceNumber\n\t\t\t\t\t: Math.min(oldestResolvedSeq, sequenceNumber);\n\t\t\tif (sequenceNumber <= target) {\n\t\t\t\treturn { kind: \"found\", base: { ...version, sequenceNumber } };\n\t\t\t}\n\t\t}\n\t\treturn { kind: \"noBaseVersion\", oldestResolvedSeq };\n\t}\n\n\tpublic async listVersions(): Promise<ResolvedVersion[]> {\n\t\tconst versions = await this.getVersions();\n\t\t// Resolution order does not matter here, so resolve concurrently; the newest-first array order is\n\t\t// preserved by Promise.all regardless of completion order.\n\t\treturn Promise.all(\n\t\t\tversions.map(async (version) => ({\n\t\t\t\t...version,\n\t\t\t\tsequenceNumber: await this.resolveSeq(version.versionId),\n\t\t\t})),\n\t\t);\n\t}\n\n\tprivate async getVersions(): Promise<OdspFileVersionRef[]> {\n\t\t// Cache the pending promise, not the awaited value, so concurrent callers share one fetch and a\n\t\t// refresh() that runs while the fetch is in flight is not overwritten when the fetch settles.\n\t\tthis.versionsCache ??= this.fetcher.listFileVersions();\n\t\treturn this.versionsCache;\n\t}\n\n\tprivate async resolveSeq(versionId: string): Promise<number> {\n\t\t// Cache the pending promise (a version's sequence number never changes) so concurrent callers\n\t\t// coalesce and a refresh() is not clobbered by a fetch that was already in flight.\n\t\tlet pending = this.seqByVersion.get(versionId);\n\t\tif (pending === undefined) {\n\t\t\tpending = this.fetcher.resolveSequenceNumber(versionId);\n\t\t\tthis.seqByVersion.set(versionId, pending);\n\t\t}\n\t\treturn pending;\n\t}\n}\n\n/**\n * Create an {@link IOdspVersionManager} for a specific ODSP file, wired to the real ODSP REST APIs.\n */\nexport function createOdspVersionManager(\n\tprops: OdspFileVersionFetcherProps,\n): IOdspVersionManager {\n\treturn new OdspVersionManager(createOdspFileVersionFetcher(props));\n}\n"]}

package/lib/packageVersion.d.ts

@@ -5,5 +5,5 @@
  * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY
  */
 export declare const pkgName = "@fluidframework/odsp-driver";
-export declare const pkgVersion = "2.111.0";
+export declare const pkgVersion = "2.112.0";
 //# sourceMappingURL=packageVersion.d.ts.map

package/lib/packageVersion.js

@@ -5,5 +5,5 @@
  * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY
  */
 export const pkgName = "@fluidframework/odsp-driver";
-export const pkgVersion = "2.111.0";
+export const pkgVersion = "2.112.0";
 //# sourceMappingURL=packageVersion.js.map

package/lib/packageVersion.js.map

@@ -1 +1 @@
-{"version":3,"file":"packageVersion.js","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,6BAA6B,CAAC;AACrD,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n *\n * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY\n */\n\nexport const pkgName = \"@fluidframework/odsp-driver\";\nexport const pkgVersion = \"2.111.0\";\n"]}
+{"version":3,"file":"packageVersion.js","sourceRoot":"","sources":["../src/packageVersion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,6BAA6B,CAAC;AACrD,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n *\n * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY\n */\n\nexport const pkgName = \"@fluidframework/odsp-driver\";\nexport const pkgVersion = \"2.112.0\";\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/odsp-driver",
-  "version": "2.111.0",
+  "version": "2.112.0",
   "description": "Socket storage implementation for SPO and ODC",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -69,27 +69,27 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.111.0",
-    "@fluidframework/core-interfaces": "~2.111.0",
-    "@fluidframework/core-utils": "~2.111.0",
-    "@fluidframework/driver-base": "~2.111.0",
-    "@fluidframework/driver-definitions": "~2.111.0",
-    "@fluidframework/driver-utils": "~2.111.0",
-    "@fluidframework/odsp-doclib-utils": "~2.111.0",
-    "@fluidframework/odsp-driver-definitions": "~2.111.0",
-    "@fluidframework/telemetry-utils": "~2.111.0",
+    "@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",
     "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.111.0",
+    "@fluid-internal/mocha-test-setup": "~2.112.0",
     "@fluid-tools/build-cli": "^0.65.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.65.0",
     "@fluidframework/eslint-config-fluid": "^13.0.0",
-    "@fluidframework/odsp-driver-previous": "npm:@fluidframework/odsp-driver@2.110.0",
+    "@fluidframework/odsp-driver-previous": "npm:@fluidframework/odsp-driver@2.111.0",
     "@microsoft/api-extractor": "7.58.1",
     "@types/mocha": "^10.0.10",
     "@types/node": "~22.19.17",

package/src/odspVersionManager/DEV.md

@@ -0,0 +1,277 @@
+# ODSP Version History Load — Design Catechism
+
+## How to read this document
+
+This spec is a **catechism**: a hierarchical series of questions and answers that is the prose
+mirror of the test suite. Each topic-level question (`###`) corresponds to a `describe` block; each
+leaf question maps to one test, linked by a stable **code ID** at the end of the answer. The same ID
+appears as a `// @q <id>` tag on the matching test.
+
+ID format: `<area>-<topic>-<nn>`. Area is `M` (the version manager — [Part II](#part-ii--the-version-manager))
+or `F` (the file-version fetcher — [Part III](#part-iii--the-file-version-fetcher)). Topic is a short
+mnemonic (e.g. `SELECT`, `RESOLVE`). `nn` is a zero-padded counter. IDs are append-only: existing IDs
+never renumber, so links stay stable across edits.
+
+The contract:
+
+- **Every leaf Q&A has a test, and every test has a leaf Q&A**, joined by its code ID. A change to
+  behavior is a change to both.
+- **This document reflects the code as it is now.** Future/aspirational work lives in
+  [Part IV — Directional](#part-iv--directional), written as questions that cannot yet be answered
+  "yes".
+
+### Terminology (legend)
+
+This code is one piece of a larger capability — letting a document be viewed or recovered at an
+earlier point in time — which spans two repositories:
+
+- **Part 1 — point-in-time load** (this repository): given a target sequence number, produce a
+  read-only view of the document at that number.
+- **Part 2 — capture & marker** (a separate host repository): record the markers that name the points
+  worth returning to. Out of scope for this document.
+
+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.
+
+## Part I — Foundations
+
+These are conceptual answers with no single test; they frame everything below.
+
+### What problem does this code solve?
+
+Given a target Fluid **sequence number** (Fluid numbers every change to a document: op 1, 2, 3, …),
+we want to materialize the document as it was at that number. The first step is choosing a **base**:
+the most recent saved version whose state is at or before the target, from which the remaining ops
+can be replayed. This code finds that base.
+
+### What is an ODSP file version, and how is it different from a Fluid snapshot?
+
+Two different things are both called a "version":
+
+- A **file version** is an entry in the file's version history — a recoverable saved state of the whole
+  file, addressed by a label such as `"42.0"`. These are what a user could restore to.
+- A **Fluid snapshot** is an internal checkpoint the runtime writes; the driver's snapshot list
+  (`getVersions`) enumerates these, not the file versions.
+
+Selecting a base uses the **file version history**, enumerated by the driveItem `/versions` API — not
+the driver's snapshot list.
+
+### Why the closest version at or before the target, rather than any earlier one?
+
+Any base at or before the target can be replayed forward to the target and yields the same state, so
+the choice is not about correctness. The **closest** one minimizes how many ops must be replayed, and
+minimizes the chance that the needed ops have been trimmed from retention. Selection therefore aims for
+the greatest version sequence number at or before the target. Because versions are enumerated
+newest-first and version order is expected to track sequence order, an early-stop scan finds it; if that
+ordering is ever violated, a valid but not-strictly-closest base may be chosen (still correct, just less
+optimal) — see [Part IV](#part-iv--directional) for the planned order-tolerant search.
+
+### How is a version's sequence number obtained?
+
+By fetching that version's snapshot from the **version-scoped snapshot endpoint**
+(`.../versions/{label}/opStream/snapshots/trees/latest?blobs=2`), which returns the snapshot in the
+driver's normal (`application/json` or `application/ms-fluid`) framing. The driver's existing snapshot
+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?
+
+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).
+
+## Part II — The Version Manager
+
+`OdspVersionManager` selects the base version. It depends on an injected `IOdspFileVersionFetcher`, so
+these behaviors are tested with an in-memory fake.
+
+### Which version does `findBaseForSeq` pick for a target sequence number?
+
+The list is newest-first, and the tip (index 0, the live document) is not a base candidate. Among the
+remaining versions, the answer is the closest one at or before the target — the greatest sequence number
+at or before the target when version order tracks sequence order, which an early-stop newest-first scan
+finds.
+
+- **Target between two versions?** The closer, older one. `M-SELECT-01`
+- **Target equal to a version?** That version, an exact match (zero ops to replay). `M-SELECT-02`
+- **Target newer than every version?** The newest recoverable version. `M-SELECT-03`
+- **Target older than every version?** `noBaseVersion`, reporting the oldest sequence number seen.
+  `M-SELECT-04`
+
+### How does it handle duplicate versions and the tip?
+
+- **Two versions share a sequence number?** Return the newest label (a metadata-only re-save leaves the
+  sequence number unchanged; the newest is closest to the head). `M-DEDUP-01`
+- **The tip (index 0)?** Never treated as a base; its sequence number is never even resolved.
+  `M-TIP-01`
+- **Only the tip exists?** `noBaseVersion`. `M-TIP-02`
+- **No versions at all?** `noBaseVersion`. `M-EMPTY-01`
+
+### What work does it avoid?
+
+- **Resolving more versions than needed?** It stops at the first version at or before the target and
+  does not resolve older ones. `M-STOP-01`
+- **Re-fetching across calls?** The version list and each resolved sequence number are cached.
+  `M-CACHE-01`
+- **Stale caches?** `refresh()` drops both the version list and the resolved sequence numbers, so the
+  next query re-enumerates and re-resolves. `M-CACHE-02`
+- **A `refresh()` while a fetch is still in flight?** The cache holds the pending fetch rather than its
+  eventual value, so a fetch that started before the refresh cannot write its now-stale result back over
+  the cleared cache; the next query re-fetches. `M-CACHE-03`
+
+### What happens when a version cannot be resolved?
+
+The failure propagates; it is never swallowed into a wrong base. `M-ERR-01`
+
+### What does `listVersions` return?
+
+Every version with its resolved sequence number, newest-first. `M-LIST-01`
+
+## Part III — The File-Version Fetcher
+
+`createOdspFileVersionFetcher` is the real `IOdspFileVersionFetcher`, talking to ODSP. Its behaviors
+are tested against a stubbed `fetch` that returns canned responses through the real request,
+authentication, and snapshot-parsing code.
+
+### How does it enumerate versions?
+
+It calls the driveItem versions URL — built from the same API root as the snapshot call — and maps the
+`value` array of each page to versions (newest-first). `F-LIST-01` A long history is paged, so it follows
+`@odata.nextLink` until it is absent and concatenates every page; a base version beyond the first page is
+therefore still found rather than mistaken for `noBaseVersion`. `F-LIST-02` A response without a `value`
+field yields an empty list rather than an error. `F-LIST-03`
+
+### How does it resolve a version's sequence number?
+
+- **A well-formed snapshot?** It calls the version-scoped snapshot URL (`.../versions/{label}/opStream/snapshots/trees/latest?blobs=2`),
+  parses the response, and returns `trees[0].sequenceNumber`. `F-RESOLVE-01`
+- **A snapshot with no sequence number?** It throws, naming the version, rather than returning a wrong
+  value. `F-RESOLVE-02`
+- **A binary (`application/ms-fluid`) snapshot?** It reads it with the driver's compact-snapshot parser
+  and returns the same sequence number the JSON path would. `F-RESOLVE-03`
+
+### How does it handle request failures?
+
+- **A non-success response while enumerating?** The failure propagates rather than being read as an
+  empty result. `F-ERROR-01`
+- **A non-success response while resolving?** Likewise, it propagates rather than yielding a wrong value.
+  `F-ERROR-03`
+- **An authentication failure while enumerating?** The shared token-refresh wrapper refreshes the token
+  and retries the request once. `F-ERROR-04`
+- **An authentication failure while resolving?** Likewise, it refreshes the token and retries once.
+  `F-ERROR-02`
+
+## Part IV — Directional
+
+Aspirational behaviors, written as questions that cannot yet be answered "yes".
+
+### Should sequence-number resolution be lazy or binary-search, rather than eager?
+
+Resolving each version costs one snapshot fetch. With up to ~50 versions, an eager newest-to-oldest
+scan can fetch more than necessary. The public contract (`findBaseForSeq`) already hides the strategy,
+so a binary search over versions could replace it without changing callers.
+
+The version list is effectively a sorted array: it is newest-first, and a version's sequence number is
+monotonically non-increasing toward older versions (a newer version is a later state). That makes it
+searchable for "the greatest sequence number at or before the target". The search must be "fuzzy" rather
+than textbook, for two reasons: versions can share a sequence number (a metadata-only re-save leaves it
+unchanged), so it is a sorted array with duplicates; and the ordering can have small local inversions.
+The robust shape is therefore binary/interpolation to get close, then a short local walk (older if the
+probe overshot the target, newer while still at or before it) to pin the exact base and absorb ties and
+inversions.
+
+Two further refinements reduce fetches. First, a version's sequence number never changes, so once
+resolved it can be cached indefinitely; refreshing only needs to reconcile which versions still exist
+(dropping ones that aged out), not re-resolve sequence numbers. Second, selection does not need the exact
+closest version — any version within a bounded number of ops of the target is "close enough", because the
+recomposed driver replays the remaining ops anyway; a tolerance lets the search stop early.
+
+### Could the version list's `lastModifiedDateTime` seed the search?
+
+Each version carries a `lastModifiedDateTime` in the list response, for free — unlike a sequence number,
+which costs a fetch to resolve. If the target is accompanied by a wall-clock time (for example, a time
+recorded when a mark was made), that timestamp does not replace the search — it replaces its **first
+probe**. Instead of starting at the blind midpoint, seed at the newest version whose
+`lastModifiedDateTime` is at or before the target time (a comparison over the already-fetched list, zero
+fetches), then converge:
+
+1. Resolve the seed version's sequence number (the first fetch).
+2. If it overshot the target (`seq > target`), step toward older versions; if it is at or before the
+   target, step toward newer versions while still at or before it — to land on the greatest sequence
+   number at or before the target.
+3. Because time, list order, and sequence number all move together, this correction is usually zero or
+   one step. If the seed is far off (large clock drift), fall back to binary search over the residual
+   interval, bounding the worst case at ~log N.
+
+The timestamp is only a seed, never the answer: time does not map linearly to sequence number (edits are
+bursty) and clocks can skew, so the neighbourhood it points to must still be pinned by resolving sequence
+numbers. Timestamps are ISO-8601 UTC; any caller-supplied time must be normalized to UTC before
+comparison. It also allows locating a version by time when no sequence number is available. This is why
+`lastModifiedDateTime` is carried on a version even though base selection itself does not use it today.
+
+
+
+### Should there be a component that loads the base and replays ops to the exact target? (Component B)
+
+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?
+
+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
+replays only the ops in `(base, T]` on top of it. Those ops come from the op stream (delta storage), and
+may also be bundled with a snapshot (the `deltas=1` query parameter, deliberately omitted here because
+the manager only needs the sequence number, not the ops).
+
+Ops in the op stream are retained for a window and can be trimmed. The resolution is not to fetch the
+trimmed ops from somewhere else — it is to **start from a newer snapshot that already absorbed them**. If
+the ops just after the base are gone but another snapshot exists later in `(base, T]`, that snapshot's
+state already includes the trimmed ops, so Component B starts there and replays only the retained tail.
+Trimmed ops are never re-fetched; a later snapshot makes them unnecessary.
+
+The target is only unreachable when all of the following hold: the nearest snapshot at or before `T` is
+old, the ops between it and `T` have been trimmed, and no snapshot falls anywhere in between to bridge
+the gap. In that case the exact state at `T` cannot be reconstructed, and Component B reports it
+(for example, a `missing ops` / not-materializable outcome) rather than returning a wrong state — a
+consumer may still choose to fall back to the nearest reachable state at or before `T`. This is rare in
+practice because snapshots are written frequently relative to the op-retention window.
+
+Note that `minimumSequenceNumber` is not the signal for any of this: it is the collaboration-window floor
+baked into a snapshot, used when a snapshot is loaded, not an indicator of which ops the op stream still
+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
+tenant credentials). An end-to-end test would exercise the real endpoints.
+
+### Should the raw driveItem `/content` download be a supported fallback?
+
+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.

package/src/odspVersionManager/index.ts

@@ -0,0 +1,12 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	createOdspVersionManager,
+	type BaseForSeq,
+	type IOdspVersionManager,
+	type OdspFileVersionRef,
+	type ResolvedVersion,
+} from "./odspVersionManager.js";