(compat) Add new interface for layer incompatibility to make it simpler for consumption by agarwal-navin · Pull Request #25706 · microsoft/FluidFramework

agarwal-navin · 2025-10-16T16:59:12Z

Also a new @alpha interface ILayerIncompatibilityError of error type FluidErrorTypes.usageError. It has properties that consumers can use to get additional details about the incompatiblity. When layer incompatibility is detected, this error will be thrown. The properties have comments that explain what these properties are for.

Also, added a telemetry called LayerIncompatibilityError which will be logged everytime layer incompatibility is detected.

AB#43990

Copilot

Pull Request Overview

Updates layer compatibility validation to produce more user-friendly errors and richer telemetry.

Introduces validateLayerCompatibility helper that centralizes logic, adds structured core properties (layer, incompatibleLayer, versions, diff) and detailed JSON errorDetails.
Exposes versions directly on telemetry properties and adds new telemetry event LayerIncompatibilityError.
Updates tests and layer type definitions (introducing FluidLayer union with lowercase layer identifiers).

Reviewed Changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/utils/telemetry-utils/src/layerCompatError.ts	Adds shared validation helper that throws UsageError, logs telemetry, and computes diff plus property sets.
packages/utils/telemetry-utils/src/index.ts	Re-exports new validateLayerCompatibility API.
packages/runtime/datastore/src/test/dataStoreLayerCompatValidation.spec.ts	Adjusts tests to new telemetry property names and casing.
packages/runtime/datastore/src/dataStoreRuntime.ts	Moves runtime compatibility validation after logger setup, passes logger.
packages/runtime/datastore/src/dataStoreLayerCompatState.ts	Refactors to use centralized helper with lowercase layer identifiers.
packages/runtime/container-runtime/src/test/runtimeLayerCompatValidation.spec.ts	Updates tests to new property names/casing and passes logger.
packages/runtime/container-runtime/src/runtimeLayerCompatState.ts	Refactors validation functions to use helper and require logger.
packages/runtime/container-runtime/src/dataStoreContext.ts	Passes logger into validation call.
packages/runtime/container-runtime/src/containerRuntime.ts	Defers loader compatibility check until logger is available.
packages/loader/container-loader/src/test/loaderLayerCompatValidation.spec.ts	Updates tests to new property names/casing and logger usage.
packages/loader/container-loader/src/loaderLayerCompatState.ts	Refactors runtime/driver validation to use helper; adds logger parameter.
packages/loader/container-loader/src/container.ts	Passes logger into validation calls.
packages/common/client-utils/src/layerCompat.ts	Introduces FluidLayer type with lowercase identifiers.
packages/common/client-utils/src/indexNode.ts	Exports FluidLayer type.
packages/common/client-utils/src/indexBrowser.ts	Exports FluidLayer type.

packages/utils/telemetry-utils/src/layerCompatError.ts

scottn12

Looks good!

packages/utils/telemetry-utils/src/layerCompatError.ts

packages/loader/container-loader/src/container.ts

packages/runtime/container-runtime/src/test/runtimeLayerCompatValidation.spec.ts

packages/runtime/datastore/src/test/dataStoreLayerCompatValidation.spec.ts

packages/runtime/datastore/src/dataStoreRuntime.ts

packages/test/test-end-to-end-tests/src/test/layerCompat.spec.ts

packages/utils/telemetry-utils/src/layerCompatError.ts

markfields

Looks good overall, left a few optional questions/comments.

packages/utils/telemetry-utils/src/layerCompatError.ts

github-actions · 2025-10-23T16:03:39Z

🔗 Found some broken links! 💔

Run a link check locally to find them. See
https://github.com/microsoft/FluidFramework/wiki/Checking-for-broken-links-in-the-documentation for more information.

linkcheck output


> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

 ELIFECYCLE  Command failed with exit code 1.

packages/common/core-interfaces/api-report/core-interfaces.legacy.beta.api.md

packages/common/core-interfaces/src/error.ts

packages/loader/container-loader/src/test/loaderLayerCompatValidation.spec.ts

packages/runtime/container-runtime/src/test/runtimeLayerCompatValidation.spec.ts

packages/utils/telemetry-utils/src/error.ts

markfields · 2025-10-23T17:01:42Z

packages/utils/telemetry-utils/src/layerCompatError.ts

+			compatibilityRequirementsInMonths:
+				compatDetailsLayer1.generation -
+				compatSupportRequirementsLayer1.minSupportedGeneration,
+			actualDifferenceInMonths:


Have we started bumping generation each month yet?

So won't this be kind of misleading? minSupportedGeneration is presumably 0, and compatDetailsLayer1.generation is presumably 1. So this will report a compat requirement of 1 month. Maybe I'm wrong in my assumptions though.

It's ok if it's a little wonky at first while getting this off the ground anyway, IMO.

In the current state, this error won't be thrown because everything is compatible. It will start throwing when we update the generation and the minSupportedGeneration.

packages/utils/telemetry-utils/src/layerCompatError.ts

markfields

left a bunch of comments on the diff since I last reviewed, hopefully they show up properly for you.

markfields

👏

Follow up to #25706. Added a new error type `layerIncompatibilityError` which will be used when a layer incompatibility is detected between Fluid layers. This will help applications detect when an error is because of layer incompatibility and take appropriate steps. The new error type is added as an legacy / alpha API. Since the `FluidErrorTypes` type is legacy / beta, added a `FluidErrorTypesAlpha` type where new error types will be added to stage them. Once the breaking change window has passed, error types will be moved to `FluidErrorTypes`. [AB#51811](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/51811)

…r for consumption (microsoft#25706) Also a new `@alpha` interface `ILayerIncompatibilityError` of error type `FluidErrorTypes.usageError`. It has properties that consumers can use to get additional details about the incompatiblity. When layer incompatibility is detected, this error will be thrown. The properties have comments that explain what these properties are for. Also, added a telemetry called `LayerIncompatibilityError` which will be logged everytime layer incompatibility is detected. [AB#43990](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/43990)

…osoft#25784) Follow up to microsoft#25706. Added a new error type `layerIncompatibilityError` which will be used when a layer incompatibility is detected between Fluid layers. This will help applications detect when an error is because of layer incompatibility and take appropriate steps. The new error type is added as an legacy / alpha API. Since the `FluidErrorTypes` type is legacy / beta, added a `FluidErrorTypesAlpha` type where new error types will be added to stage them. Once the breaking change window has passed, error types will be moved to `FluidErrorTypes`. [AB#51811](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/51811)

Copilot AI review requested due to automatic review settings October 16, 2025 16:59

github-actions bot added area: loader Loader related issues area: runtime Runtime related issues labels Oct 16, 2025

agarwal-navin requested review from markfields and scottn12 October 16, 2025 16:59

github-actions bot added the base: main PRs targeted against main branch label Oct 16, 2025

Copilot AI reviewed Oct 16, 2025

View reviewed changes

packages/utils/telemetry-utils/src/layerCompatError.ts Outdated Show resolved Hide resolved

packages/utils/telemetry-utils/src/layerCompatError.ts Show resolved Hide resolved

packages/utils/telemetry-utils/src/layerCompatError.ts Outdated Show resolved Hide resolved

scottn12 approved these changes Oct 16, 2025

View reviewed changes

packages/utils/telemetry-utils/src/layerCompatError.ts Outdated Show resolved Hide resolved

packages/utils/telemetry-utils/src/layerCompatError.ts Outdated Show resolved Hide resolved

github-actions bot added the area: tests Tests to add, test infrastructure improvements, etc label Oct 16, 2025

agarwal-navin force-pushed the layerCompatError branch from 3b432ca to 0d47a13 Compare October 16, 2025 20:59

agarwal-navin added 3 commits October 16, 2025 13:59

(compat) Update the layer validation error to be more user friendly

14af677

Update end-to-end tests

13d4c84

Fix unit tests

51d5c64

agarwal-navin force-pushed the layerCompatError branch from 0d47a13 to 51d5c64 Compare October 16, 2025 20:59

PR comments

9161078

markfields reviewed Oct 22, 2025

View reviewed changes

packages/loader/container-loader/src/container.ts Show resolved Hide resolved

markfields reviewed Oct 22, 2025

View reviewed changes

packages/runtime/container-runtime/src/test/runtimeLayerCompatValidation.spec.ts Show resolved Hide resolved

markfields reviewed Oct 22, 2025

View reviewed changes

packages/runtime/datastore/src/test/dataStoreLayerCompatValidation.spec.ts Outdated Show resolved Hide resolved

markfields reviewed Oct 22, 2025

View reviewed changes

packages/runtime/datastore/src/dataStoreRuntime.ts Show resolved Hide resolved

markfields reviewed Oct 22, 2025

View reviewed changes

packages/test/test-end-to-end-tests/src/test/layerCompat.spec.ts Outdated Show resolved Hide resolved

markfields reviewed Oct 22, 2025

View reviewed changes

packages/utils/telemetry-utils/src/layerCompatError.ts Show resolved Hide resolved

markfields reviewed Oct 22, 2025

View reviewed changes

packages/utils/telemetry-utils/src/layerCompatError.ts Show resolved Hide resolved

markfields reviewed Oct 22, 2025

View reviewed changes

packages/utils/telemetry-utils/src/layerCompatError.ts Outdated Show resolved Hide resolved

markfields reviewed Oct 22, 2025

View reviewed changes

packages/utils/telemetry-utils/src/layerCompatError.ts Outdated Show resolved Hide resolved

markfields approved these changes Oct 22, 2025

View reviewed changes

PR comments 2

72bce83

markfields reviewed Oct 22, 2025

View reviewed changes

packages/utils/telemetry-utils/src/layerCompatError.ts Show resolved Hide resolved

markfields approved these changes Oct 22, 2025

View reviewed changes

agarwal-navin added 2 commits October 22, 2025 14:14

Revert changes to error telemetry

662006b

Add new error type for layer incompatibility

232aa3c

agarwal-navin requested a review from a team as a code owner October 23, 2025 00:36

github-actions bot added the public api change Changes to a public API label Oct 23, 2025

agarwal-navin changed the title ~~(compat) Add new error type for layer incomatibility to make it easier to consume~~ (compat) Add new interface for layer incomatibility to make it simpler for consumption Oct 23, 2025

agarwal-navin added 2 commits October 22, 2025 17:38

Merge branch 'main' into layerCompatError

5582cc7

Fix tests

7156365