@fluidframework/runtime-utils 2.118.0 → 3.0.0

package/CHANGELOG.md

@@ -1,12 +1,42 @@
 # @fluidframework/runtime-utils
 
-## 2.118.0
+## 3.0.0
 
-Dependency updates only.
+### Minor Changes
 
-## 2.117.0
+- Removal of direct CommonJS support ([#28124](https://github.com/microsoft/FluidFramework/pull/28124)) [0f84e3b8878](https://github.com/microsoft/FluidFramework/commit/0f84e3b8878a5e75b2253976d98fd963bbd9db88)
 
-Dependency updates only.
+  Direct `require()` import is no longer directly supported.
+  Package is transpiled as ECMAScript Module.
+
+  See [Removal of direct CommonJS support in v3.0](https://github.com/microsoft/FluidFramework/issues/27444) for more information.
+
+- Require modern TypeScript module resolution ([#27970](https://github.com/microsoft/FluidFramework/pull/27970)) [325e2016ca9](https://github.com/microsoft/FluidFramework/commit/325e2016ca9978d4a1f7552c97ba34feac9df41f)
+
+  Fluid Framework Client packages no longer include type declaration compatibility entrypoints for TypeScript's legacy Node10 resolution mode (`"moduleResolution": "node"` or `"node10"`).
+  Applications upgrading to Fluid Framework 3.0 must use one of the following supported configurations:
+  - `"module": "Node16"` with `"moduleResolution": "Node16"`
+  - `"module": "NodeNext"` with `"moduleResolution": "NodeNext"`
+  - `"module": "ESNext"` with `"moduleResolution": "Bundler"`
+
+  Existing public package entrypoints exposed through `package.json` exports, including `/alpha`, `/beta`, and `/legacy`, remain available under supported module resolution modes.
+
+  See [Removal of Node10 resolutions in v3.0](https://github.com/microsoft/FluidFramework/issues/27457) for more information.
+
+- Client packages now target ES2022 ([#27846](https://github.com/microsoft/FluidFramework/pull/27846)) [91c78541bdd](https://github.com/microsoft/FluidFramework/commit/91c78541bddcbca5d6c5f357b023eeaee617d885)
+
+  The TypeScript compilation `target` and `lib` for the Fluid Framework client packages have been raised from ES2021/ES2020 to **ES2022**.
+  The published JavaScript now uses ES2022 language features (with correspondingly less down-leveling), so consuming these packages requires a runtime that supports ES2022.
+  All actively supported Node.js versions and evergreen browsers already meet this requirement.
+
+  Note that Fluid Framework has not officially supported targets older than ES2022 since before 2.0: this is documented in [ClientRequirements.md](https://github.com/microsoft/FluidFramework/blob/main/ClientRequirements.md) as well as the README for every client package.
+
+  It is possible this change could impact users of less up to date JavaScript runtimes.
+  Impacted users can use a tool like [babel](https://babeljs.io/) to transpile out unsupported language features.
+
+- Build with TypeScript 6 ([#28052](https://github.com/microsoft/FluidFramework/pull/28052)) [7ab015c49de](https://github.com/microsoft/FluidFramework/commit/7ab015c49deec84833cdfe1fb5e1606b901f6e81)
+
+  FluidFramework Client SDK is now built using TypeScript 6. Consumers should build with TypeScript v6 or v7 or compatible tooling.
 
 ## 2.116.0
 

package/README.md

@@ -9,15 +9,15 @@ This package contains code for common utilities used by Fluid Framework runtimes
 
 ## Using Fluid Framework libraries
 
-When taking a dependency on a Fluid Framework library's public APIs, we recommend using a `^` (caret) version range, such as `^1.3.4`.
-While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries,
-library consumers should always prefer `^`.
+For a dependency on a Fluid Framework library's public APIs, we recommend a `^` (caret) version range.
+For example, use `^1.3.4`.
 
-If using any of Fluid Framework's unstable APIs (for example, its `beta` APIs), we recommend using a more constrained version range, such as `~`.
+For a dependency on an unstable API, such as a `beta` API, we recommend a more restrictive version range.
+For example, use a `~` version range.
 
 ## Installation
 
-To get started, install the package by running the following command:
+Run this command to install the package:
 
 ```bash
 npm i @fluidframework/runtime-utils
@@ -25,16 +25,16 @@ npm i @fluidframework/runtime-utils
 
 ## Importing from this package
 
-This package leverages [package.json exports](https://nodejs.org/api/packages.html#exports) to separate its APIs by support level.
-For more information on the related support guarantees, see [API Support Levels](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels).
+This package uses [package.json exports](https://nodejs.org/api/packages.html#exports) to separate APIs by support level.
+For information about the support guarantees, read [API Support Levels](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels).
 
-To access the `public` ([SemVer](https://semver.org/)) APIs, import via `@fluidframework/runtime-utils` like normal.
+Import the `public` APIs from `@fluidframework/runtime-utils`.
 
-To access the `legacy` APIs, import via `@fluidframework/runtime-utils/legacy`.
+Import the `legacy` APIs from `@fluidframework/runtime-utils/legacy`.
 
 ## API Documentation
 
-API documentation for **@fluidframework/runtime-utils** is available at <https://fluidframework.com/docs/apis/runtime-utils>.
+Read the **@fluidframework/runtime-utils** API documentation at <https://fluidframework.com/docs/apis/runtime-utils>.
 
 <!-- prettier-ignore-end -->
 
@@ -47,62 +47,69 @@ API documentation for **@fluidframework/runtime-utils** is available at <https:/
 
 ## Minimum Client Requirements
 
-These are the platform requirements for the current version of Fluid Framework Client Packages.
-These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter.
-For Long Term Support (LTS) versions this can require supporting these platforms for several years.
+Fluid Framework client libraries support the platforms in this document.
+These requirements are intentionally restrictive.
+Within a major version series, we can relax these requirements, but we cannot make them stricter.
+For a Long Term Support (LTS) version, we might need to support these platforms for several years.
 
-It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug.
-If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request.
-When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working.
+Other configurations can work, but Fluid Framework does not support them.
+If an unsupported configuration stops working, we do not classify this as a bug.
+To request support for a configuration that is not listed, file an issue.
+The product team will evaluate your request.
+In the issue, specify the current status of the configuration:
+
+-   The configuration works but needs official support.
+-   The configuration does not work and requires changes.
 
 ### Supported Runtimes
 
--   NodeJs ^22.22.2 except that we will drop support for it [when NodeJs 22 loses its upstream support on 2027-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS at least 1 year before 22 is end-of-life.
-    -   Running Fluid in a Node.js environment with the `--no-experimental-fetch` flag is not supported.
--   Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards).
+-   Fluid Framework supports Node.js versions 22 and 24 while they receive [upstream support](https://nodejs.org/en/about/previous-releases).
+    -   Fluid Framework will stop support for version 22 [when upstream support ends on 2027-04-30](https://github.com/nodejs/release#release-schedule).
+    -   Fluid Framework does not support Node.js with the `--no-experimental-fetch` flag.
+-   Fluid Framework supports modern browsers that support the ES2022 standard library.
 
 ### Supported Tools
 
--   TypeScript 5.4:
-    -   All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported.
-    -   [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required.
-    -   [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported.
-    -   `exactOptionalPropertyTypes` is currently not fully supported.
-        If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases.
+-   [TypeScript 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0):
+    -   Fluid Framework supports all [`strict`](https://www.typescriptlang.org/tsconfig) options.
+    -   Set the build targets (`lib`, `target`) to `ES2022` or later.
+    -   Enable [`strictNullChecks`](https://www.typescriptlang.org/tsconfig).
+    -   Fluid Framework does not support [configuration options deprecated in TypeScript 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0#breaking-changes-and-deprecations-in-typescript-6-0).
+    -   Fluid Framework does not fully support `exactOptionalPropertyTypes`.
+        If you enable this option, do not use `in`, `Reflect.has`, `Object.hasOwn`, or `Object.prototype.hasOwnProperty` to narrow members of Fluid Framework types.
+        These methods can incorrectly exclude `undefined` from the possible values.
 -   [webpack](https://webpack.js.org/) 5
-    -   We are not intending to be prescriptive about what bundler to use.
-        Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test.
+    -   We do not require a specific bundler.
+        Other bundlers that handle ES Modules can work, but we actively test only webpack.
 
 ### Module Resolution
 
-[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm).
-Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development.
+In TypeScript `compilerOptions`, use [`Node16`, `Node20`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) module resolution.
+These settings follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm).
+
+Do not use `Node10` module resolution.
 
 ### Module Formats
 
 -   ES Modules:
-    ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported.
--   CommonJs:
-    Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below.
-    This is done to accommodate some workflows without good ES Module support.
-    If you have a workflow you would like included in this list, file an issue.
-    Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here.
-
-    -   Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648))
+    Use ES Modules to consume Fluid Framework client packages, including in Node.js.
+-   CommonJS:
+    Fluid Framework does not officially support CommonJS in version 3.0 or later.
 
 ## Contribution Guidelines
 
-There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid.
+You can [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid Framework in these ways:
 
--   Participate in Q&A in our [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
--   [Submit bugs](https://github.com/microsoft/FluidFramework/issues) and help us verify fixes as they are checked in.
--   Review the [source code changes](https://github.com/microsoft/FluidFramework/pulls).
+-   Answer questions in [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
+-   [Submit bug reports](https://github.com/microsoft/FluidFramework/issues) and help verify fixes.
+-   Review [source code changes](https://github.com/microsoft/FluidFramework/pulls).
 -   [Contribute bug fixes](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md).
 
-Detailed instructions for working in the repo can be found in the [Wiki](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md).
+For detailed instructions, read the [repo documentation](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md).
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+This project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information, read the [Code of Conduct frequently asked questions](https://opensource.microsoft.com/codeofconduct/faq/).
+For questions or comments, contact [opencode@microsoft.com](mailto:opencode@microsoft.com).
 
 This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
 Use of these trademarks or logos must follow Microsoft’s [Trademark & Brand Guidelines](https://www.microsoft.com/trademarks).
@@ -110,13 +117,9 @@ Use of Microsoft trademarks or logos in modified versions of this project must n
 
 ## Help
 
-Not finding what you're looking for in this README?
-Check out [fluidframework.com](https://fluidframework.com/docs/).
-
-Still not finding what you're looking for?
-Please [file an issue](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Contributing/Submitting-Bugs-and-Feature-Requests.md).
+Read the [Fluid Framework documentation](https://fluidframework.com/docs/) for information about Fluid Framework concepts and APIs.
 
-Thank you!
+To request information that the documentation does not contain, [create an issue](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Contributing/Submitting-Bugs-and-Feature-Requests.md).
 
 ## Trademark
 

package/{api-extractor.json → api-extractor/api-extractor-model.json}

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-model.esm.json"
+	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-model.esm.json"
 }

package/dist/compatibilityBase.d.ts

@@ -4,51 +4,36 @@
  */
 import type { OldestSupportedClientVersion } from "@fluidframework/runtime-definitions/internal";
 /**
- * Our policy is to support major versions N and N-1, where N is most
- * recent public major release of the Fluid Framework Client.
- * Therefore, if the customer does not provide a minVersionForCollab, we will
- * default to use N-1.
- *
- * However, this is not consistent with today's behavior. Some options (i.e.
- * batching, compression) are enabled by default despite not being compatible
- * with 1.x clients. Since the policy was introduced during 2.x's lifespan,
- * N/N-1 compatibility by **default** will be in effect starting with 3.0.
- * Importantly though, N/N-2 compatibility is still guaranteed with the proper
- * configurations set.
- *
- * Further to distinguish unspecified `minVersionForCollab` from a specified
- * version and allow `enableExplicitSchemaControl` to default to `true` for
- * any 2.0.0+ version, we will use a special value of `2.0.0-defaults`, which
- * is semantically less than 2.0.0.
+ * Oldest deployed Fluid Framework client version supported for cross-client compatibility.
  *
  * @internal
  */
-export declare const defaultMinVersionForCollab: "2.0.0-defaults";
+export declare const lowestMinVersionForCollab: "2.0.0";
 /**
- * We don't want allow a version before the major public release of the LTS version.
- * Today we use "1.0.0", because our policy supports N/N-1 & N/N-2, which includes
- * all minor versions of N. Though LTS starts at 1.4.0, we should stay consistent
- * with our policy and allow all 1.x versions to be compatible with 2.x.
+ * Default oldest supported client for APIs that still permit the setting to be omitted.
  *
- * @privateRemarks
- * Exported for use in tests.
+ * @remarks
+ * This aliases {@link lowestMinVersionForCollab} in Client 3.0. Remove this fallback when
+ * customer-facing APIs require `oldestSupportedClient` in Client 3.10.
+ * See {@link https://github.com/microsoft/FluidFramework/issues/27180}.
  *
  * @internal
  */
-export declare const lowestMinVersionForCollab: "1.0.0";
+export declare const defaultMinVersionForCollab: "2.0.0";
 /**
- * String in a valid semver format specifying bottom of a minor version
- * or special "defaults" prerelease of a major.
- * @remarks Only 2.0.0-defaults is expected, but index signatures cannot be a
- * literal; so, just allow any major -defaults prerelease.
+ * String in a valid semver format specifying the bottom of a minor version.
+ *
+ * @remarks
+ * Configuration maps use major/minor checkpoints. Exact patch and prerelease versions are values
+ * supplied to the selection logic, not configuration-map keys.
  *
  * @internal
  */
-export type MinimumMinorSemanticVersion = `${bigint}.${bigint}.0` | `${bigint}.0.0-defaults`;
+export type MinimumMinorSemanticVersion = `${bigint}.${bigint}.0`;
 /**
  * String in a valid semver format of a specific version at least specifying minor.
- * Unlike {@link @fluidframework/runtime-definitions#OldestSupportedClientVersion}, this type allows any bigint for the major version.
- * Used as a more generic type that allows major versions other than 1 or 2.
+ * Unlike {@link @fluidframework/runtime-definitions#OldestSupportedClientVersion}, this type does
+ * not encode the active compatibility floor or major-specific patch restrictions.
  *
  * @internal
  */
@@ -134,6 +119,7 @@ export declare function checkValidMinVersionForCollabVerbose(minVersionForCollab
     isValidSemver: boolean;
     isGteLowestMinVersion: boolean;
     isLtePkgVersion: boolean;
+    isValidOldestSupportedClientVersion: boolean;
 };
 /**
  * Checks if the minVersionForCollab is valid.
@@ -143,32 +129,21 @@ export declare function checkValidMinVersionForCollabVerbose(minVersionForCollab
  */
 export declare function isValidMinVersionForCollab(minVersionForCollab: SemanticVersion): minVersionForCollab is OldestSupportedClientVersion;
 /**
- * `pkgVersion` version without pre-release.
+ * `pkgVersion` version without pre-release and with zeroed patch.
  * @remarks
- * This is the version that the code in the current version of the codebase will have when officially released.
- * Generally, compatibility of prerelease builds is not guaranteed (especially for how they interact with future releases).
- * So while technically a prerelease build is less (older) than the released version which follows it and thus supports less features,
- * it makes sense for them to claim to support the same features as the following release so they can be used to test how the release would actually behave.
- *
- * To accomplish this, the version the next release will have is provided here as `cleanedPackageVersion` while `pkgVersion` may be a prerelease in some cases,
- * like when running tests on CI, or in an actual prerelease published package.
- * This is then used in {@link validateMinimumVersionForCollab} to allow the version shown on main to be usable as a `minVersionForCollab`, even in CI and prerelease packages.
+ * This is the version the current codebase will have when officially released.
+ * It allows CI and prerelease builds to test the release's features using that version as their
+ * `OldestSupportedClientVersion`.
  *
- * This is of particular note in two cases:
- * 1. When landing a new feature, and setting the minVersionForCollab which enables it to be the version that the next release will have.
- * Having that version be valid on main, pass tests locally, then fail on CI and when using published prerelease packages would be confusing, and probably undesired.
- * 2. Setting the minVersionForCollab to the current version for scenarios that do no involve collab with other package versions seems like it should be valid.
- * This is useful for testing new features, and also non collaborative scenarios where the latest features are desired.
- *
- * To accommodate some uses of the second case, it might be useful to package export this in the future.
+ * Code that needs to derive this value from a package version should use
+ * {@link @fluidframework/driver-definitions#featureVersion}.
  *
  * @privateRemarks
- * Since this is used by validateMinimumVersionForCollab, the type case to OldestSupportedClientVersion can not use it directly.
- * Thus this is just `as` cast here, and a test confirms it is valid according to validateMinimumVersionForCollab.
+ * This value is validated against {@link validateMinimumVersionForCollab} by a test.
  *
  * @internal
  */
-export declare const cleanedPackageVersion: OldestSupportedClientVersion;
+export declare const cleanedPackageVersion: "3.0.0";
 /**
  * Narrows the type of the provided {@link SemanticVersion} to a {@link @fluidframework/runtime-definitions#OldestSupportedClientVersion}, throwing a UsageError if it is not valid.
  * @remarks
@@ -184,14 +159,12 @@ export declare function validateMinimumVersionForCollab(semanticVersion: string)
 /**
  * Validates the given `overrides`.
  *
- * No-op when minVersionForCollab is set to defaultMinVersionForCollab.
- *
- * Otherwise this checks that for keys which are in both the `validationMap` and the `overrides`,
+ * Checks that for keys which are in both the `validationMap` and the `overrides`,
  * that the `validationMap` function for that key either returns undefined or a version less than or equal to `minVersionForCollab`.
  * @privateRemarks
  * This design seems odd, and might want to be revisited.
  * Currently it only permits opting out of features, not into them (unless validationMap returns undefined),
- * and the handling of defaultMinVersionForCollab and undefined versions seems questionable.
+ * and the handling of undefined versions seems questionable.
  * Also ignoring of extra keys in overrides might be bad since it seems like overrides is supposed to be validated.
  * @internal
  */

package/dist/compatibilityBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compatibilityBase.d.ts","sourceRoot":"","sources":["../src/compatibilityBase.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compatibilityBase.d.ts","sourceRoot":"","sources":["../src/compatibilityBase.ts"],"names":[],"mappings":"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"}

package/dist/compatibilityBase.js

@@ -4,44 +4,38 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.configValueToMinVersionForCollab = exports.validateConfigMapOverrides = exports.validateMinimumVersionForCollab = exports.cleanedPackageVersion = exports.isValidMinVersionForCollab = exports.checkValidMinVersionForCollabVerbose = exports.selectVersionRoundedDown = exports.getConfigForMinVersionForCollabIterable = exports.getConfigForMinVersionForCollab = exports.getConfigsForMinVersionForCollab = exports.lowestMinVersionForCollab = exports.defaultMinVersionForCollab = void 0;
+exports.cleanedPackageVersion = exports.defaultMinVersionForCollab = exports.lowestMinVersionForCollab = void 0;
+exports.getConfigsForMinVersionForCollab = getConfigsForMinVersionForCollab;
+exports.getConfigForMinVersionForCollab = getConfigForMinVersionForCollab;
+exports.getConfigForMinVersionForCollabIterable = getConfigForMinVersionForCollabIterable;
+exports.selectVersionRoundedDown = selectVersionRoundedDown;
+exports.checkValidMinVersionForCollabVerbose = checkValidMinVersionForCollabVerbose;
+exports.isValidMinVersionForCollab = isValidMinVersionForCollab;
+exports.validateMinimumVersionForCollab = validateMinimumVersionForCollab;
+exports.validateConfigMapOverrides = validateConfigMapOverrides;
+exports.configValueToMinVersionForCollab = configValueToMinVersionForCollab;
 const internal_1 = require("@fluidframework/core-utils/internal");
 const internal_2 = require("@fluidframework/telemetry-utils/internal");
+const internal_3 = require("@fluidframework/driver-definitions/internal");
 const semver_ts_1 = require("semver-ts");
 const packageVersion_js_1 = require("./packageVersion.js");
 /**
- * Our policy is to support major versions N and N-1, where N is most
- * recent public major release of the Fluid Framework Client.
- * Therefore, if the customer does not provide a minVersionForCollab, we will
- * default to use N-1.
- *
- * However, this is not consistent with today's behavior. Some options (i.e.
- * batching, compression) are enabled by default despite not being compatible
- * with 1.x clients. Since the policy was introduced during 2.x's lifespan,
- * N/N-1 compatibility by **default** will be in effect starting with 3.0.
- * Importantly though, N/N-2 compatibility is still guaranteed with the proper
- * configurations set.
- *
- * Further to distinguish unspecified `minVersionForCollab` from a specified
- * version and allow `enableExplicitSchemaControl` to default to `true` for
- * any 2.0.0+ version, we will use a special value of `2.0.0-defaults`, which
- * is semantically less than 2.0.0.
+ * Oldest deployed Fluid Framework client version supported for cross-client compatibility.
  *
  * @internal
  */
-exports.defaultMinVersionForCollab = "2.0.0-defaults";
+exports.lowestMinVersionForCollab = "2.0.0";
 /**
- * We don't want allow a version before the major public release of the LTS version.
- * Today we use "1.0.0", because our policy supports N/N-1 & N/N-2, which includes
- * all minor versions of N. Though LTS starts at 1.4.0, we should stay consistent
- * with our policy and allow all 1.x versions to be compatible with 2.x.
+ * Default oldest supported client for APIs that still permit the setting to be omitted.
  *
- * @privateRemarks
- * Exported for use in tests.
+ * @remarks
+ * This aliases {@link lowestMinVersionForCollab} in Client 3.0. Remove this fallback when
+ * customer-facing APIs require `oldestSupportedClient` in Client 3.10.
+ * See {@link https://github.com/microsoft/FluidFramework/issues/27180}.
  *
  * @internal
  */
-exports.lowestMinVersionForCollab = "1.0.0";
+exports.defaultMinVersionForCollab = exports.lowestMinVersionForCollab;
 /**
  * Returns a default configuration given minVersionForCollab and configuration version map.
  *
@@ -60,7 +54,6 @@ function getConfigsForMinVersionForCollab(minVersionForCollab, configMap) {
     // We have populated every key, so casting away the Partial is now safe:
     return defaultConfigs;
 }
-exports.getConfigsForMinVersionForCollab = getConfigsForMinVersionForCollab;
 /**
  * Returns a default configuration given minVersionForCollab and {@link ConfigMapEntry}.
  *
@@ -69,7 +62,6 @@ exports.getConfigsForMinVersionForCollab = getConfigsForMinVersionForCollab;
 function getConfigForMinVersionForCollab(minVersionForCollab, config) {
     return getConfigForMinVersionForCollabIterable(minVersionForCollab, Object.entries(config));
 }
-exports.getConfigForMinVersionForCollab = getConfigForMinVersionForCollab;
 /**
  * Returns a default configuration given minVersionForCollab and the contents of a {@link ConfigMapEntry} in an Iterable.
  * @remarks
@@ -90,7 +82,6 @@ function getConfigForMinVersionForCollabIterable(minVersionForCollab, entries) {
     return (selectVersionRoundedDown(minVersionForCollab, versions) ??
         (0, internal_1.fail)(0xcb8 /* No config map entry for version */))[1];
 }
-exports.getConfigForMinVersionForCollabIterable = getConfigForMinVersionForCollabIterable;
 /**
  * Finds the entry for the highest version that is less than or equal to the provided minVersionForCollab.
  * @remarks
@@ -114,7 +105,6 @@ function selectVersionRoundedDown(minVersionForCollab, entries, compareVersions
     }
     return undefined;
 }
-exports.selectVersionRoundedDown = selectVersionRoundedDown;
 /**
  * Returns detailed information about the validity of a minVersionForCollab.
  * @param minVersionForCollab - The minVersionForCollab to validate.
@@ -123,15 +113,22 @@ exports.selectVersionRoundedDown = selectVersionRoundedDown;
  * @internal
  */
 function checkValidMinVersionForCollabVerbose(minVersionForCollab) {
-    const isValidSemver = (0, semver_ts_1.valid)(minVersionForCollab) !== null;
+    const parsed = (0, semver_ts_1.parse)(minVersionForCollab);
+    const isValidSemver = parsed !== null && parsed.build.length === 0;
+    const isGteLowestMinVersion = isValidSemver && (0, semver_ts_1.gte)(minVersionForCollab, exports.lowestMinVersionForCollab);
+    const isLtePkgVersion = isValidSemver && (0, semver_ts_1.lte)(minVersionForCollab, exports.cleanedPackageVersion);
+    const isValidOldestSupportedClientVersion = isGteLowestMinVersion &&
+        isLtePkgVersion &&
+        parsed !== null &&
+        parsed.prerelease.length === 0 &&
+        (parsed.major < 3 || parsed.patch === 0);
     return {
         isValidSemver,
-        // We have to check if the value is a valid semver before calling gte/lte, otherwise they will throw when parsing the version.
-        isGteLowestMinVersion: isValidSemver && (0, semver_ts_1.gte)(minVersionForCollab, exports.lowestMinVersionForCollab),
-        isLtePkgVersion: isValidSemver && (0, semver_ts_1.lte)(minVersionForCollab, exports.cleanedPackageVersion),
+        isGteLowestMinVersion,
+        isLtePkgVersion,
+        isValidOldestSupportedClientVersion,
     };
 }
-exports.checkValidMinVersionForCollabVerbose = checkValidMinVersionForCollabVerbose;
 /**
  * Checks if the minVersionForCollab is valid.
  * A valid minVersionForCollab is a OldestSupportedClientVersion that is at least `lowestMinVersionForCollab` and less than or equal to the current package version.
@@ -139,38 +136,25 @@ exports.checkValidMinVersionForCollabVerbose = checkValidMinVersionForCollabVerb
  * @internal
  */
 function isValidMinVersionForCollab(minVersionForCollab) {
-    const { isValidSemver, isGteLowestMinVersion, isLtePkgVersion } = checkValidMinVersionForCollabVerbose(minVersionForCollab);
-    return isValidSemver && isGteLowestMinVersion && isLtePkgVersion;
+    return checkValidMinVersionForCollabVerbose(minVersionForCollab)
+        .isValidOldestSupportedClientVersion;
 }
-exports.isValidMinVersionForCollab = isValidMinVersionForCollab;
-const parsedPackageVersion = (0, semver_ts_1.parse)(packageVersion_js_1.pkgVersion) ?? (0, internal_1.fail)(0xcb9 /* Invalid package version */);
 /**
- * `pkgVersion` version without pre-release.
+ * `pkgVersion` version without pre-release and with zeroed patch.
  * @remarks
- * This is the version that the code in the current version of the codebase will have when officially released.
- * Generally, compatibility of prerelease builds is not guaranteed (especially for how they interact with future releases).
- * So while technically a prerelease build is less (older) than the released version which follows it and thus supports less features,
- * it makes sense for them to claim to support the same features as the following release so they can be used to test how the release would actually behave.
- *
- * To accomplish this, the version the next release will have is provided here as `cleanedPackageVersion` while `pkgVersion` may be a prerelease in some cases,
- * like when running tests on CI, or in an actual prerelease published package.
- * This is then used in {@link validateMinimumVersionForCollab} to allow the version shown on main to be usable as a `minVersionForCollab`, even in CI and prerelease packages.
+ * This is the version the current codebase will have when officially released.
+ * It allows CI and prerelease builds to test the release's features using that version as their
+ * `OldestSupportedClientVersion`.
  *
- * This is of particular note in two cases:
- * 1. When landing a new feature, and setting the minVersionForCollab which enables it to be the version that the next release will have.
- * Having that version be valid on main, pass tests locally, then fail on CI and when using published prerelease packages would be confusing, and probably undesired.
- * 2. Setting the minVersionForCollab to the current version for scenarios that do no involve collab with other package versions seems like it should be valid.
- * This is useful for testing new features, and also non collaborative scenarios where the latest features are desired.
- *
- * To accommodate some uses of the second case, it might be useful to package export this in the future.
+ * Code that needs to derive this value from a package version should use
+ * {@link @fluidframework/driver-definitions#featureVersion}.
  *
  * @privateRemarks
- * Since this is used by validateMinimumVersionForCollab, the type case to OldestSupportedClientVersion can not use it directly.
- * Thus this is just `as` cast here, and a test confirms it is valid according to validateMinimumVersionForCollab.
+ * This value is validated against {@link validateMinimumVersionForCollab} by a test.
  *
  * @internal
  */
-exports.cleanedPackageVersion = `${parsedPackageVersion.major}.${parsedPackageVersion.minor}.${parsedPackageVersion.patch}`;
+exports.cleanedPackageVersion = (0, internal_3.featureVersion)(packageVersion_js_1.pkgVersion);
 /**
  * Narrows the type of the provided {@link SemanticVersion} to a {@link @fluidframework/runtime-definitions#OldestSupportedClientVersion}, throwing a UsageError if it is not valid.
  * @remarks
@@ -184,36 +168,29 @@ exports.cleanedPackageVersion = `${parsedPackageVersion.major}.${parsedPackageVe
  */
 function validateMinimumVersionForCollab(semanticVersion) {
     const minVersionForCollab = semanticVersion;
-    const { isValidSemver, isGteLowestMinVersion, isLtePkgVersion } = checkValidMinVersionForCollabVerbose(minVersionForCollab);
-    if (!(isValidSemver && isGteLowestMinVersion && isLtePkgVersion)) {
+    const { isValidSemver, isGteLowestMinVersion, isLtePkgVersion, isValidOldestSupportedClientVersion, } = checkValidMinVersionForCollabVerbose(minVersionForCollab);
+    if (!isValidOldestSupportedClientVersion) {
         throw new internal_2.UsageError(`Version ${minVersionForCollab} is not a valid OldestSupportedClientVersion. ` +
             `It must be in a valid semver format, at least ${exports.lowestMinVersionForCollab}, ` +
-            `and less than or equal to the current package version ${exports.cleanedPackageVersion}. ` +
-            `Details: { isValidSemver: ${isValidSemver}, isGteLowestMinVersion: ${isGteLowestMinVersion}, isLtePkgVersion: ${isLtePkgVersion} }`);
+            `less than or equal to the current package version ${exports.cleanedPackageVersion}, ` +
+            `have no prerelease component, and use patch version 0 for major version 3 and later. ` +
+            `Use "featureVersion" to normalize a package version to the correct format. ` +
+            `Details: { isValidSemver: ${isValidSemver}, isGteLowestMinVersion: ${isGteLowestMinVersion}, isLtePkgVersion: ${isLtePkgVersion}, isValidOldestSupportedClientVersion: ${isValidOldestSupportedClientVersion} }`);
     }
 }
-exports.validateMinimumVersionForCollab = validateMinimumVersionForCollab;
 /**
  * Validates the given `overrides`.
  *
- * No-op when minVersionForCollab is set to defaultMinVersionForCollab.
- *
- * Otherwise this checks that for keys which are in both the `validationMap` and the `overrides`,
+ * Checks that for keys which are in both the `validationMap` and the `overrides`,
  * that the `validationMap` function for that key either returns undefined or a version less than or equal to `minVersionForCollab`.
  * @privateRemarks
  * This design seems odd, and might want to be revisited.
  * Currently it only permits opting out of features, not into them (unless validationMap returns undefined),
- * and the handling of defaultMinVersionForCollab and undefined versions seems questionable.
+ * and the handling of undefined versions seems questionable.
  * Also ignoring of extra keys in overrides might be bad since it seems like overrides is supposed to be validated.
  * @internal
  */
 function validateConfigMapOverrides(minVersionForCollab, overrides, validationMap) {
-    if (minVersionForCollab === exports.defaultMinVersionForCollab) {
-        // If the minVersionForCollab is set to the default value, then we will not validate the runtime options
-        // This is to avoid disruption to users who have not yet set the minVersionForCollab value explicitly.
-        // TODO: This also skips validation for users which explicitly request defaultMinVersionForCollab which seems like a bug.
-        return;
-    }
     // Iterate through each runtime option passed in by the user
     // Type assertion is safe as entries come from runtimeOptions object
     for (const [passedRuntimeOption, passedRuntimeOptionValue] of Object.entries(overrides)) {
@@ -229,7 +206,6 @@ function validateConfigMapOverrides(minVersionForCollab, overrides, validationMa
         }
     }
 }
-exports.validateConfigMapOverrides = validateConfigMapOverrides;
 /**
  * Helper function to map ContainerRuntimeOptionsInternal config values to
  * minVersionForCollab in, e.g., {@link @fluidframework/container-runtime#runtimeOptionsAffectingDocSchemaConfigValidationMap}.
@@ -267,5 +243,4 @@ function configValueToMinVersionForCollab(configToMinVer) {
         return undefined;
     };
 }
-exports.configValueToMinVersionForCollab = configValueToMinVersionForCollab;
 //# sourceMappingURL=compatibilityBase.js.map