Update how shared tree codec versions are generated (#25752)

This change updates how the write version for the different codecs in
tree are determined.
Currently, there is a mapping of `SharedTreeFormatVersion` to a list of
write versions for all codecs. The `SharedTreeFormatVersion` is one of
the options that can be passed when creating a tree and the codecs
version are selected from the mapping based on this value.

With this change, `SharedTreeFormatVersion` will be removed. Instead,
the write versions for the codecs will be selected based on the
`minVersionForCollab` option that is also passed during tree creation.
The `minVersionForCollab` will be passed down to each codec and it can
decide what write version it wants based on this.

This PR also standardizes how the various versions are maintained by the
codecs (using an `as const` enum-like object and branded values, and a
function that generates the right version based on the
`minVersionForCollab`).

The mapping from `SharedTreeFormatVersion` to `minVersionForCollab` is
as follows:
* `SharedTreeFormatVersion.v1`: no longer an option
* `SharedTreeFormatVersion.v2`: no longer an option
* `SharedTreeFormatVersion.v3`: `minVersionForCollab:
FluidClientVersion.v2_0`
* `SharedTreeFormatVersion.v4`: was never an option, still not an option
* `SharedTreeFormatVersion.v5`: `minVersionForCollab:
FluidClientVersion.v2_43`
* `SharedTreeFormatVersion.vSharedBranches`: no longer an option. Use
`SharedTreeOptions.enableSharedBranches` instead.

Unchanged: specifying `minVersionForCollab: FluidClientVersion.v2_52`
will enable `DetachedFieldIndexFormatVersion.v2`.


[AB#51463](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/51463).

## Breaking Changes

`SharedTreeFormatOptions` (internal) no longer has a `formatVersion`
field.

---------

Co-authored-by: yann-achard-MS <97201204+yann-achard-MS@users.noreply.github.com>

Author: agarwal-navin

.changeset/big-items-stop.md

@@ -0,0 +1,22 @@
+---
+"@fluidframework/tree": minor
+"fluid-framework": minor
+"__section": tree
+---
+`formatVersion` removed from the options passed to `configuredSharedTree`
+
+Note: this change may break users of alpha APIs. See below for details.
+
+`SharedTreeOptions` (which is passed to `configuredSharedTree`) no longer includes a `formatVersion: SharedTreeFormatVersion[keyof SharedTreeFormatVersion]` field.
+The concept of `SharedTreeFormatVersion` has been removed altogether.
+Instead, users are expected to leverage the already existing `minVersionForCollab` field.
+
+For migration purposes, the mapping from `SharedTreeFormatVersion` to `minVersionForCollab` is as follows:
+* `SharedTreeFormatVersion.v1`: no supported equivalent
+* `SharedTreeFormatVersion.v2`: no supported equivalent
+* `SharedTreeFormatVersion.v3`: `minVersionForCollab: FluidClientVersion.v2_0`
+* `SharedTreeFormatVersion.v5`: `minVersionForCollab: FluidClientVersion.v2_43`
+* `SharedTreeFormatVersion.vSharedBranches`: `minVersionForCollab: FluidClientVersion.v2_43` + `SharedTreeOptions.enableSharedBranches`
+
+The values for which there is no supported equivalent `minVersionForCollab` were never given official support.
+[Contact](https://github.com/microsoft/FluidFramework/issues) the Fluid Framework team if you need help migrating away from them.

packages/dds/tree/api-report/tree.alpha.api.md

@@ -320,6 +320,7 @@ type FlexListToUnion<TList extends FlexList> = ExtractItemType<TList[number]>;
 // @alpha
 export const FluidClientVersion: {
     readonly v2_0: "2.0.0";
+    readonly v2_43: "2.43.0";
     readonly v2_52: "2.52.0";
 };
 
@@ -998,7 +999,6 @@ type ScopedSchemaName<TScope extends string | undefined, TName extends number |
 
 // @alpha @input
 export interface SharedTreeFormatOptions {
-    formatVersion: SharedTreeFormatVersion[keyof SharedTreeFormatVersion];
     treeEncodeType: TreeCompressionStrategy;
 }
 
@@ -1015,7 +1015,9 @@ export const SharedTreeFormatVersion: {
 export type SharedTreeFormatVersion = typeof SharedTreeFormatVersion;
 
 // @alpha @input
-export type SharedTreeOptions = Partial<CodecWriteOptions> & Partial<SharedTreeFormatOptions> & SharedTreeOptionsBeta;
+export interface SharedTreeOptions extends Partial<CodecWriteOptions>, Partial<SharedTreeFormatOptions>, SharedTreeOptionsBeta {
+    readonly enableSharedBranches?: boolean;
+}
 
 // @beta @input
 export type SharedTreeOptionsBeta = ForestOptions;

packages/dds/tree/src/codec/codec.ts

@@ -499,9 +499,23 @@ export const FluidClientVersion = {
 	// then update it to "2.001" once we actually have the opt in working.
 	// v2_1 = v2_0,
 
-	/** Fluid Framework Client 2.52 and newer. */
-	// New formats introduced in 2.52:
-	// - DetachedFieldIndex FormatV2
+	/**
+	 * Fluid Framework Client 2.43 and newer.
+	 *
+	 * New formats introduced in 2.43:
+	 * - SchemaFormatVersion.v2
+	 * - MessageFormatVersion.v4
+	 * - EditManagerFormatVersion.v4
+	 * - Sequence format version 3
+	 */
+	v2_43: "2.43.0",
+
+	/**
+	 * Fluid Framework Client 2.52 and newer.
+	 *
+	 * New formats introduced in 2.52:
+	 * - DetachedFieldIndexFormatVersion.v2
+	 */
 	v2_52: "2.52.0",
 } as const satisfies Record<string, MinimumVersionForCollab>;
 

packages/dds/tree/src/core/index.ts

@@ -151,8 +151,7 @@ export {
 	type SchemaAndPolicy,
 	Multiplicity,
 	type SchemaPolicy,
-	SchemaVersion,
-	type SchemaFormatVersion,
+	SchemaFormatVersion,
 } from "./schema-stored/index.js";
 
 export {

packages/dds/tree/src/core/schema-stored/index.ts

@@ -23,8 +23,7 @@ export {
 	storedSchemaDecodeDispatcher,
 	type SchemaAndPolicy,
 	type SchemaPolicy,
-	SchemaVersion,
-	type SchemaFormatVersion,
+	SchemaFormatVersion,
 } from "./schema.js";
 export {
 	type TreeStoredSchemaSubscription,

packages/dds/tree/src/core/schema-stored/schema.ts

@@ -33,14 +33,17 @@ import type { Multiplicity } from "./multiplicity.js";
 /**
  * The format version for the schema.
  */
-export enum SchemaVersion {
-	v1 = 1,
+export const SchemaFormatVersion = {
+	v1: 1,
 	/**
 	 * Adds persisted metadata to the node schema and field schema.
 	 */
-	v2 = 2,
-}
-export type SchemaFormatVersion = Brand<SchemaVersion, "SchemaFormatVersion">;
+	v2: 2,
+} as const;
+export type SchemaFormatVersion = Brand<
+	(typeof SchemaFormatVersion)[keyof typeof SchemaFormatVersion],
+	"SchemaFormatVersion"
+>;
 
 type FieldSchemaFormat = FieldSchemaFormatV1 | FieldSchemaFormatV2;
 

packages/dds/tree/src/core/tree/detachedFieldIndexCodecCommon.ts

@@ -12,6 +12,7 @@ import { hasSingle } from "../../util/index.js";
 
 import {
 	Format,
+	type DetachedFieldIndexFormatVersion,
 	type EncodedRootsForRevision,
 	type RootRanges,
 } from "./detachedFieldIndexFormatCommon.js";
@@ -27,7 +28,7 @@ import type { Static, TSchema } from "@sinclair/typebox";
 export function makeDetachedFieldIndexCodecFromMajorCodec<
 	TEncodedRevisionTag,
 	TEncodedRevisionTagSchema extends TSchema,
-	TVersion extends number,
+	TVersion extends DetachedFieldIndexFormatVersion,
 >(
 	options: ICodecOptions,
 	majorCodec: IJsonCodec<Major, TEncodedRevisionTag>,

packages/dds/tree/src/core/tree/detachedFieldIndexCodecV1.ts

@@ -14,9 +14,11 @@ import {
 	RevisionTagSchema,
 } from "../rebase/index.js";
 
-import { type FormatV1, version1 } from "./detachedFieldIndexFormatV1.js";
+import type { FormatV1 } from "./detachedFieldIndexFormatV1.js";
 import type { DetachedFieldSummaryData, Major } from "./detachedFieldIndexTypes.js";
 import { makeDetachedFieldIndexCodecFromMajorCodec } from "./detachedFieldIndexCodecCommon.js";
+import { DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
+import { brand } from "../../util/index.js";
 
 class MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {
 	public constructor(
@@ -74,7 +76,7 @@ export function makeDetachedNodeToFieldCodecV1(
 	return makeDetachedFieldIndexCodecFromMajorCodec(
 		options,
 		majorCodec,
-		version1,
+		brand(DetachedFieldIndexFormatVersion.v1),
 		RevisionTagSchema,
 	);
 }

packages/dds/tree/src/core/tree/detachedFieldIndexCodecV2.ts

@@ -9,14 +9,12 @@ import type { IIdCompressor, StableId } from "@fluidframework/id-compressor";
 import type { ICodecOptions, IJsonCodec } from "../../codec/index.js";
 import type { EncodedRevisionTag, RevisionTagCodec, RevisionTag } from "../rebase/index.js";
 
-import {
-	type FormatV2,
-	StableOrFinalRevisionTag,
-	version2,
-} from "./detachedFieldIndexFormatV2.js";
+import { type FormatV2, StableOrFinalRevisionTag } from "./detachedFieldIndexFormatV2.js";
 import type { DetachedFieldSummaryData, Major } from "./detachedFieldIndexTypes.js";
 import { makeDetachedFieldIndexCodecFromMajorCodec } from "./detachedFieldIndexCodecCommon.js";
 import { isStableId } from "@fluidframework/id-compressor/internal";
+import { DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
+import { brand } from "../../util/index.js";
 
 class MajorCodec implements IJsonCodec<Major> {
 	public constructor(
@@ -66,7 +64,7 @@ export function makeDetachedNodeToFieldCodecV2(
 	return makeDetachedFieldIndexCodecFromMajorCodec(
 		options,
 		majorCodec,
-		version2,
+		brand(DetachedFieldIndexFormatVersion.v2),
 		StableOrFinalRevisionTag,
 	);
 }

packages/dds/tree/src/core/tree/detachedFieldIndexCodecs.ts

@@ -4,6 +4,7 @@
  */
 
 import type { IIdCompressor } from "@fluidframework/id-compressor";
+import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 
 import {
 	type CodecTree,
@@ -16,22 +17,35 @@ import {
 } from "../../codec/index.js";
 import type { RevisionTagCodec } from "../rebase/index.js";
 
-import { version1 } from "./detachedFieldIndexFormatV1.js";
-import { version2 } from "./detachedFieldIndexFormatV2.js";
 import { makeDetachedNodeToFieldCodecV1 } from "./detachedFieldIndexCodecV1.js";
 import { makeDetachedNodeToFieldCodecV2 } from "./detachedFieldIndexCodecV2.js";
 import type { DetachedFieldSummaryData } from "./detachedFieldIndexTypes.js";
-import type { Brand } from "../../util/index.js";
+import { DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
+import { brand } from "../../util/index.js";
+
+/**
+ * Convert a MinimumVersionForCollab to a version for detached field codecs.
+ * @param clientVersion - The MinimumVersionForCollab to convert.
+ * @returns The detached field codec version that corresponds to the provided MinimumVersionForCollab.
+ */
+function clientVersionToDetachedFieldVersion(
+	clientVersion: MinimumVersionForCollab,
+): DetachedFieldIndexFormatVersion {
+	return clientVersion < FluidClientVersion.v2_52
+		? brand(DetachedFieldIndexFormatVersion.v1)
+		: brand(DetachedFieldIndexFormatVersion.v2);
+}
 
 export function makeDetachedFieldIndexCodec(
 	revisionTagCodec: RevisionTagCodec,
 	options: CodecWriteOptions,
 	idCompressor: IIdCompressor,
 ): IJsonCodec<DetachedFieldSummaryData> {
 	const family = makeDetachedFieldIndexCodecFamily(revisionTagCodec, options, idCompressor);
-	const writeVersion =
-		options.minVersionForCollab < FluidClientVersion.v2_52 ? version1 : version2;
-	return makeVersionDispatchingCodec(family, { ...options, writeVersion });
+	return makeVersionDispatchingCodec(family, {
+		...options,
+		writeVersion: clientVersionToDetachedFieldVersion(options.minVersionForCollab),
+	});
 }
 
 export function makeDetachedFieldIndexCodecFamily(
@@ -40,14 +54,22 @@ export function makeDetachedFieldIndexCodecFamily(
 	idCompressor: IIdCompressor,
 ): ICodecFamily<DetachedFieldSummaryData> {
 	return makeCodecFamily([
-		[version1, makeDetachedNodeToFieldCodecV1(revisionTagCodec, options, idCompressor)],
-		[version2, makeDetachedNodeToFieldCodecV2(revisionTagCodec, options, idCompressor)],
+		[
+			DetachedFieldIndexFormatVersion.v1,
+			makeDetachedNodeToFieldCodecV1(revisionTagCodec, options, idCompressor),
+		],
+		[
+			DetachedFieldIndexFormatVersion.v2,
+			makeDetachedNodeToFieldCodecV2(revisionTagCodec, options, idCompressor),
+		],
 	]);
 }
 
-export type DetachedFieldIndexFormatVersion = Brand<1 | 2, "DetachedFieldIndexFormatVersion">;
 export function getCodecTreeForDetachedFieldIndexFormat(
-	version: DetachedFieldIndexFormatVersion,
+	clientVersion: MinimumVersionForCollab,
 ): CodecTree {
-	return { name: "DetachedFieldIndex", version };
+	return {
+		name: "DetachedFieldIndex",
+		version: clientVersionToDetachedFieldVersion(clientVersion),
+	};
 }