Compat: Add minVersionForCollab option to declarative model and deprecate CompatibilityMode

[scottn12]

Description

This PR updates the declarative model to accept any (valid) minVersionForCollab. This is intended to replace the existing CompatibilityMode type (deprecated in this PR), which accepts either "1" or "2". This was done to ensure the declarative model is aligned to support the latest changes to the cross-client compat policy (see #27064).

The following are the major changes in this PR:

• MinimumVersionForCollab promoted from a beta to public API. This was done so it could be used in public declarative model APIs.
• CompatibilityMode param in createDOProviderContainerRuntimeFactory() now also acceptsMinimumVersionForCollab (previously only the CompatibilityMode type).
• Deprecated CompatibilityMode type (will be removed in 3.0).
• Deprecated minVersionForCollabOverride (will be removed in 3.0).

Reviewer Guidance

• Promoting MinimumVersionForCollab will require API council review. If it's easier, this can be split into a separate PR.

Misc

AB#72040

[github-actions]

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (310 lines, 25 files), I've queued these reviewers:

• Correctness — logic errors, race conditions, lifecycle issues
• Security — vulnerabilities, secret exposure, injection
• API Compatibility — breaking changes, release tags, type design
• Performance — algorithmic regressions, memory leaks
• Testing — coverage gaps, hollow tests

Toggle the reviewer checkboxes above to adjust, then tick the box below to start:

• Start review

[Copilot]

Pull request overview

This PR updates the Fluid declarative model and service client APIs to support specifying an explicit minVersionForCollab (now aligned with the newer cross-client compatibility policy), while deprecating the legacy CompatibilityMode abstraction.

Changes:

• Promote MinimumVersionForCollab to a @public API in @fluidframework/runtime-definitions.
• Add optional minVersionForCollab?: MinimumVersionForCollab parameters to Tinylicious/Azure client container create/load flows and plumb through to the declarative model runtime factory creation.
• Deprecate CompatibilityMode (and minVersionForCollabOverride) while keeping compatibilityMode required for now to select runtime defaults.

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds workspace links for @fluidframework/runtime-definitions where newly imported.
packages/service-clients/tinylicious-client/src/TinyliciousClient.ts	Adds minVersionForCollab param and forwards it into runtime factory creation.
packages/service-clients/tinylicious-client/package.json	Adds dependency on @fluidframework/runtime-definitions.
packages/service-clients/tinylicious-client/api-report/tinylicious-client.public.api.md	Reflects new optional minVersionForCollab API surface.
packages/service-clients/tinylicious-client/api-report/tinylicious-client.beta.api.md	Reflects new optional minVersionForCollab API surface.
packages/service-clients/tinylicious-client/api-report/tinylicious-client.alpha.api.md	Reflects new optional minVersionForCollab API surface.
packages/service-clients/end-to-end-tests/azure-client/src/test/AzureClientFactory.ts	Updates test factory typing to include optional minVersionForCollab.
packages/service-clients/azure-client/src/interfaces.ts	Extends internal factory hook typing to accept optional minVersionForCollab.
packages/service-clients/azure-client/src/AzureClient.ts	Adds minVersionForCollab param(s) and forwards into runtime factory creation.
packages/service-clients/azure-client/package.json	Adds dependency on @fluidframework/runtime-definitions.
packages/service-clients/azure-client/api-report/azure-client.public.api.md	Reflects new optional minVersionForCollab API surface and deprecates CompatibilityMode export.
packages/service-clients/azure-client/api-report/azure-client.legacy.public.api.md	Same as public API report for legacy build.
packages/service-clients/azure-client/api-report/azure-client.legacy.beta.api.md	Same as public API report for legacy beta build.
packages/service-clients/azure-client/api-report/azure-client.beta.api.md	Same as public API report for beta build.
packages/runtime/runtime-definitions/src/compatibilityDefinitions.ts	Promotes MinimumVersionForCollab from @beta to @public.
packages/runtime/runtime-definitions/api-report/runtime-definitions.public.api.md	API report updated to include MinimumVersionForCollab as public.
packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.public.api.md	API report updated to include MinimumVersionForCollab as public.
packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.beta.api.md	Updates extracted tag for MinimumVersionForCollab to public.
packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.alpha.api.md	Updates extracted tag for MinimumVersionForCollab to public.
packages/runtime/runtime-definitions/api-report/runtime-definitions.beta.api.md	Updates extracted tag for MinimumVersionForCollab to public.
packages/framework/fluid-static/src/utils.ts	Introduces helper to resolve min-version and runtime defaults; keeps compatibility-mode mapping.
packages/framework/fluid-static/src/types.ts	Marks CompatibilityMode deprecated in favor of minVersionForCollab.
packages/framework/fluid-static/src/treeRootDataObject.ts	Plumbs minVersionForCollab through declarative tree runtime factory creation.
packages/framework/fluid-static/src/rootDataObject.ts	Plumbs minVersionForCollab through declarative DO-provider runtime factory creation.
packages/framework/fluid-static/src/compatibilityConfiguration.ts	Adds deprecated-import lint suppression for now-deprecated CompatibilityMode.
packages/framework/fluid-static/api-report/fluid-static.public.api.md	Marks CompatibilityMode deprecated in extracted API.
packages/framework/fluid-static/api-report/fluid-static.legacy.public.api.md	Marks CompatibilityMode deprecated in extracted legacy API.
packages/framework/fluid-static/api-report/fluid-static.legacy.beta.api.md	Marks CompatibilityMode deprecated and reflects added minVersionForCollab param in legacy beta API.
packages/framework/fluid-static/api-report/fluid-static.beta.api.md	Marks CompatibilityMode deprecated in extracted beta API.
packages/framework/fluid-static/api-report/fluid-static.alpha.api.md	Marks CompatibilityMode deprecated in extracted alpha API.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[jason-ha]

Rather than keeping these two types separate, where practical in API surface have them as a single input.

• Internally, at the outermost bottleneck filter for CompatibilityMode and convert to the appropriate min version.
• In API be sure to note what values are deprecated since most callers are using a CompatibilityMode enumeration.
  • Be sure to update in repo use to the non-deprecated pattern. (Do a test build where CompatibilityMode doesn't exist. That change can be kept in a branch that stages the breaking change.)

[scottn12]

Rather than keeping these two types separate, where practical in API surface have them as a single input.

• Internally, at the outermost bottleneck filter for CompatibilityMode and convert to the appropriate min version.

• In API be sure to note what values are deprecated since most callers are using a CompatibilityMode enumeration.

  • Be sure to update in repo use to the non-deprecated pattern. (Do a test build where CompatibilityMode doesn't exist. That change can be kept in a branch that stages the breaking change.)

@jason-ha, updated in latest to do this

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

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

Crawling...

Stats:
  288641 links
    1922 destination URLs
    2172 URLs ignored
       0 warnings
       0 errors