@fluidframework/tree 2.51.0 → 2.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.51.0",
+  "version": "2.52.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -101,17 +101,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.51.0",
-    "@fluidframework/container-runtime": "~2.51.0",
-    "@fluidframework/core-interfaces": "~2.51.0",
-    "@fluidframework/core-utils": "~2.51.0",
-    "@fluidframework/datastore-definitions": "~2.51.0",
-    "@fluidframework/driver-definitions": "~2.51.0",
-    "@fluidframework/id-compressor": "~2.51.0",
-    "@fluidframework/runtime-definitions": "~2.51.0",
-    "@fluidframework/runtime-utils": "~2.51.0",
-    "@fluidframework/shared-object-base": "~2.51.0",
-    "@fluidframework/telemetry-utils": "~2.51.0",
+    "@fluid-internal/client-utils": "~2.52.0",
+    "@fluidframework/container-runtime": "~2.52.0",
+    "@fluidframework/core-interfaces": "~2.52.0",
+    "@fluidframework/core-utils": "~2.52.0",
+    "@fluidframework/datastore-definitions": "~2.52.0",
+    "@fluidframework/driver-definitions": "~2.52.0",
+    "@fluidframework/id-compressor": "~2.52.0",
+    "@fluidframework/runtime-definitions": "~2.52.0",
+    "@fluidframework/runtime-utils": "~2.52.0",
+    "@fluidframework/shared-object-base": "~2.52.0",
+    "@fluidframework/telemetry-utils": "~2.52.0",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@types/ungap__structured-clone": "^1.2.0",
@@ -121,20 +121,20 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.51.0",
-    "@fluid-private/stochastic-test-utils": "~2.51.0",
-    "@fluid-private/test-dds-utils": "~2.51.0",
-    "@fluid-private/test-drivers": "~2.51.0",
+    "@fluid-internal/mocha-test-setup": "~2.52.0",
+    "@fluid-private/stochastic-test-utils": "~2.52.0",
+    "@fluid-private/test-dds-utils": "~2.52.0",
+    "@fluid-private/test-drivers": "~2.52.0",
     "@fluid-tools/benchmark": "^0.51.0",
-    "@fluid-tools/build-cli": "^0.56.0",
+    "@fluid-tools/build-cli": "^0.57.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.56.0",
-    "@fluidframework/container-definitions": "~2.51.0",
-    "@fluidframework/container-loader": "~2.51.0",
+    "@fluidframework/build-tools": "^0.57.0",
+    "@fluidframework/container-definitions": "~2.52.0",
+    "@fluidframework/container-loader": "~2.52.0",
     "@fluidframework/eslint-config-fluid": "^5.7.4",
-    "@fluidframework/test-runtime-utils": "~2.51.0",
-    "@fluidframework/test-utils": "~2.51.0",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.50.0",
+    "@fluidframework/test-runtime-utils": "~2.52.0",
+    "@fluidframework/test-utils": "~2.52.0",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.51.0",
     "@microsoft/api-extractor": "7.52.8",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",

package/src/codec/codec.ts

@@ -409,9 +409,10 @@ export enum FluidClientVersion {
 	// then update it to "2.001" once we actually have the opt in working.
 	// v2_1 = v2_0,
 
-	/** Fluid Framework Client 2.41 and newer. */
-	// If we land some new formats in 2.41, we can enable selecting
-	// v2_41 = 2.041,
+	/** Fluid Framework Client 2.52 and newer. */
+	// New formats introduced in 2.52:
+	// - DetachedFieldIndex FormatV2
+	v2_52 = 2.052,
 
 	/**
 	 * Enable unreleased and unfinished features.

package/src/core/index.ts

@@ -192,10 +192,12 @@ export {
 	revisionMetadataSourceFromInfo,
 	type RevisionInfo,
 	type EncodedRevisionTag,
+	type EncodedStableId,
 	type EncodedChangeAtomId,
 	taggedAtomId,
 	taggedOptAtomId,
 	offsetChangeAtomId,
+	StableIdSchema,
 	subtractChangeAtomIds,
 	replaceAtomRevisions,
 	replaceChange,

package/src/core/rebase/index.ts

@@ -16,6 +16,7 @@ export {
 	RevisionTagSchema,
 	type EncodedRevisionTag,
 	type EncodedChangeAtomId,
+	type EncodedStableId,
 	type ChangesetLocalId,
 	type ChangeAtomId,
 	type ChangeAtomIdMap,
@@ -23,6 +24,7 @@ export {
 	taggedAtomId,
 	taggedOptAtomId,
 	offsetChangeAtomId,
+	StableIdSchema,
 	subtractChangeAtomIds,
 	replaceAtomRevisions,
 	type ChangeAtomIdRangeMap,

package/src/core/rebase/types.ts

@@ -7,6 +7,7 @@ import type {
 	OpSpaceCompressedId,
 	SessionId,
 	SessionSpaceCompressedId,
+	StableId,
 } from "@fluidframework/id-compressor";
 import { Type } from "@sinclair/typebox";
 
@@ -38,6 +39,9 @@ export const RevisionTagSchema = Type.Union([
 	brandedNumberType<Exclude<EncodedRevisionTag, string>>(),
 ]);
 
+export type EncodedStableId = Brand<StableId, "EncodedStableId">;
+export const StableIdSchema = Type.String();
+
 /**
  * An ID which is unique within a revision of a `ModularChangeset`.
  * A `ModularChangeset` which is a composition of multiple revisions may contain duplicate `ChangesetLocalId`s,

package/src/core/schema-stored/schema.ts

@@ -110,9 +110,6 @@ export interface SchemaAndPolicy {
  * This contains information that describes the semantics of things which can be referenced in stored schema.
  * For example, field kind identifiers refer to specific field kinds, which imply specific rules around what is valid in a given field (the multiplicity).
  * This structure provides such information, allowing it to be possible to determine if a given tree complies with a particular stored schema.
- *
- * TODO: AB#43546
- * Some additional data which is not needed to define compatibility with a given stored schema is currently included here, and should be removed.
  */
 export interface SchemaPolicy {
 	/**
@@ -123,27 +120,6 @@ export interface SchemaPolicy {
 	 * and will be unable to process any changes that use those FieldKinds.
 	 */
 	readonly fieldKinds: ReadonlyMap<FieldKindIdentifier, FieldKindData>;
-
-	/**
-	 * If true, new content inserted into the tree should be validated against the stored schema.
-	 * @remarks
-	 * TODO: AB#43546: This is not information used to interpret the stored schema: this configuration should be moved elsewhere.
-	 */
-	readonly validateSchema: boolean;
-
-	/**
-	 * Whether to allow a document to be opened when a particular stored schema (identified by `identifier`)
-	 * contains optional fields that are not known to the view schema.
-	 *
-	 * @privateRemarks
-	 * Plumbing this in via `SchemaPolicy` avoids needing to walk the view schema representation repeatedly in places
-	 * that need it (schema validation, view vs stored compatibility checks).
-	 *
-	 * TODO: AB#43546
-	 * This is not information used to interpret the stored schema: it is instead about view schema, and how compatible they are with a stored schema.
-	 * SchemaCompatibilityTester should be updated to not store this table in here, and then this field should be removed.
-	 */
-	allowUnknownOptionalFields(identifier: TreeNodeSchemaIdentifier): boolean;
 }
 
 /**
@@ -179,7 +155,7 @@ export interface TreeFieldStoredSchema {
  *
  * 2. The schema used for out of schema fields (which thus must be empty/not exist) on object and leaf nodes.
  */
-export const forbiddenFieldKindIdentifier = "Forbidden";
+export const forbiddenFieldKindIdentifier: FieldKindIdentifier = brand("Forbidden");
 
 /**
  * A schema for empty fields (fields which must always be empty).
@@ -187,7 +163,7 @@ export const forbiddenFieldKindIdentifier = "Forbidden";
  */
 export const storedEmptyFieldSchema: TreeFieldStoredSchema = {
 	// This kind requires the field to be empty.
-	kind: brand(forbiddenFieldKindIdentifier),
+	kind: forbiddenFieldKindIdentifier,
 	// This type set also forces the field to be empty not not allowing any types as all.
 	types: new Set(),
 	persistedMetadata: undefined,

package/src/core/tree/detachedFieldIndex.ts

@@ -28,8 +28,6 @@ import type { RevisionTag, RevisionTagCodec } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type * as Delta from "./delta.js";
-import { makeDetachedNodeToFieldCodec } from "./detachedFieldIndexCodec.js";
-import type { Format } from "./detachedFieldIndexFormat.js";
 import type {
 	DetachedField,
 	DetachedFieldSummaryData,
@@ -37,6 +35,7 @@ import type {
 	Major,
 	Minor,
 } from "./detachedFieldIndexTypes.js";
+import { makeDetachedFieldIndexCodec } from "./detachedFieldIndexCodecs.js";
 
 /**
  * The tree index records detached field IDs and associates them with a change atom ID.
@@ -59,7 +58,7 @@ export class DetachedFieldIndex {
 		Delta.DetachedNodeId
 	> = new Map();
 
-	private readonly codec: IJsonCodec<DetachedFieldSummaryData, Format>;
+	private readonly codec: IJsonCodec<DetachedFieldSummaryData>;
 	private readonly options: CodecWriteOptions;
 
 	/**
@@ -87,8 +86,7 @@ export class DetachedFieldIndex {
 			jsonValidator: noopValidator,
 			oldestCompatibleClient: FluidClientVersion.v2_0,
 		};
-		// TODO: this should take in CodecWriteOptions, and use it to pick the write version.
-		this.codec = makeDetachedNodeToFieldCodec(revisionTagCodec, this.options, idCompressor);
+		this.codec = makeDetachedFieldIndexCodec(revisionTagCodec, this.options, idCompressor);
 	}
 
 	public clone(): DetachedFieldIndex {
@@ -337,7 +335,7 @@ export class DetachedFieldIndex {
 	 * Loads the tree index from the given string, this overrides any existing data.
 	 */
 	public loadData(data: JsonCompatibleReadOnly): void {
-		const detachedFieldIndex: DetachedFieldSummaryData = this.codec.decode(data as Format);
+		const detachedFieldIndex: DetachedFieldSummaryData = this.codec.decode(data);
 
 		this.rootIdAllocator = idAllocatorFromMaxId(
 			detachedFieldIndex.maxId,

package/src/core/tree/detachedFieldIndexCodecCommon.ts

@@ -0,0 +1,87 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	type ICodecOptions,
+	type IJsonCodec,
+	makeVersionedValidatedCodec,
+} from "../../codec/index.js";
+import { hasSingle } from "../../util/index.js";
+
+import {
+	Format,
+	type EncodedRootsForRevision,
+	type RootRanges,
+} from "./detachedFieldIndexFormatCommon.js";
+import type {
+	DetachedField,
+	DetachedFieldSummaryData,
+	Major,
+} from "./detachedFieldIndexTypes.js";
+import type { Static, TSchema } from "@sinclair/typebox";
+
+// Return type is intentionally derived.
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function makeDetachedFieldIndexCodecFromMajorCodec<
+	TEncodedRevisionTag,
+	TEncodedRevisionTagSchema extends TSchema,
+	TVersion extends number,
+>(
+	options: ICodecOptions,
+	majorCodec: IJsonCodec<Major, TEncodedRevisionTag>,
+	version: TVersion,
+	encodedRevisionTagSchema: TEncodedRevisionTagSchema,
+) {
+	const formatSchema = Format(version, encodedRevisionTagSchema);
+	return makeVersionedValidatedCodec(options, new Set([version]), formatSchema, {
+		encode: (data: DetachedFieldSummaryData): Static<typeof formatSchema> => {
+			const rootsForRevisions: EncodedRootsForRevision[] = [];
+			for (const [major, innerMap] of data.data) {
+				const encodedRevision = majorCodec.encode(major);
+				const rootRanges: RootRanges = [];
+				for (const [minor, detachedField] of innerMap) {
+					rootRanges.push([minor, detachedField.root]);
+				}
+				if (hasSingle(rootRanges)) {
+					const firstRootRange = rootRanges[0];
+					const rootsForRevision: EncodedRootsForRevision = [
+						encodedRevision,
+						firstRootRange[0],
+						firstRootRange[1],
+					];
+					rootsForRevisions.push(rootsForRevision);
+				} else {
+					const rootsForRevision: EncodedRootsForRevision = [encodedRevision, rootRanges];
+					rootsForRevisions.push(rootsForRevision);
+				}
+			}
+			const encoded: Static<typeof formatSchema> = {
+				version,
+				data: rootsForRevisions,
+				maxId: data.maxId,
+			};
+			return encoded;
+		},
+		decode: (parsed: Static<typeof formatSchema>): DetachedFieldSummaryData => {
+			const map = new Map();
+			for (const rootsForRevision of parsed.data) {
+				const innerMap = new Map<number, DetachedField>();
+				if (rootsForRevision.length === 2) {
+					for (const [minor, root] of rootsForRevision[1]) {
+						innerMap.set(minor, { root });
+					}
+				} else {
+					innerMap.set(rootsForRevision[1], { root: rootsForRevision[2] });
+				}
+				const revision = rootsForRevision[0] as TEncodedRevisionTag;
+				map.set(majorCodec.decode(revision), innerMap);
+			}
+			return {
+				data: map,
+				maxId: parsed.maxId,
+			};
+		},
+	});
+}

package/src/core/tree/{detachedFieldIndexCodec.ts → detachedFieldIndexCodecV1.ts}

@@ -6,27 +6,19 @@
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
+import type { ICodecOptions, IJsonCodec } from "../../codec/index.js";
 import {
-	type ICodecOptions,
-	type IJsonCodec,
-	makeVersionedValidatedCodec,
-} from "../../codec/index.js";
-import { hasSingle } from "../../util/index.js";
-import type { EncodedRevisionTag, RevisionTagCodec, RevisionTag } from "../rebase/index.js";
+	type EncodedRevisionTag,
+	type RevisionTagCodec,
+	type RevisionTag,
+	RevisionTagSchema,
+} from "../rebase/index.js";
 
-import {
-	type EncodedRootsForRevision,
-	Format,
-	type RootRanges,
-	version,
-} from "./detachedFieldIndexFormat.js";
-import type {
-	DetachedField,
-	DetachedFieldSummaryData,
-	Major,
-} from "./detachedFieldIndexTypes.js";
+import { type FormatV1, version1 } from "./detachedFieldIndexFormatV1.js";
+import type { DetachedFieldSummaryData, Major } from "./detachedFieldIndexTypes.js";
+import { makeDetachedFieldIndexCodecFromMajorCodec } from "./detachedFieldIndexCodecCommon.js";
 
-class MajorCodec implements IJsonCodec<Major> {
+class MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {
 	public constructor(
 		private readonly revisionTagCodec: RevisionTagCodec,
 		private readonly options: ICodecOptions,
@@ -48,6 +40,10 @@ class MajorCodec implements IJsonCodec<Major> {
 		 * This assert is valid because the revision for an acked edit will have already been finalized, and a revision
 		 * for a local-only edit will be finalizable at summarization time (local edits can only occur on a summarizing client
 		 * if they're created while detached, and local ids made while detached are finalized before generating the attach summary).
+		 *
+		 * WARNING: the above is true when the whole container transitions from detached to attached,
+		 * but not when the container is already attached and it's just the shared-tree that is attaching.
+		 * The assert below will fail in such a scenario. This is addressed in the v2 codec.
 		 */
 		assert(
 			id === "root" || id >= 0,
@@ -69,58 +65,16 @@ class MajorCodec implements IJsonCodec<Major> {
 	}
 }
 
-export function makeDetachedNodeToFieldCodec(
+export function makeDetachedNodeToFieldCodecV1(
 	revisionTagCodec: RevisionTagCodec,
 	options: ICodecOptions,
 	idCompressor: IIdCompressor,
-): IJsonCodec<DetachedFieldSummaryData, Format> {
+): IJsonCodec<DetachedFieldSummaryData, FormatV1> {
 	const majorCodec = new MajorCodec(revisionTagCodec, options, idCompressor);
-	return makeVersionedValidatedCodec(options, new Set([version]), Format, {
-		encode: (data: DetachedFieldSummaryData): Format => {
-			const rootsForRevisions: EncodedRootsForRevision[] = [];
-			for (const [major, innerMap] of data.data) {
-				const encodedRevision = majorCodec.encode(major);
-				const rootRanges: RootRanges = [];
-				for (const [minor, detachedField] of innerMap) {
-					rootRanges.push([minor, detachedField.root]);
-				}
-				if (hasSingle(rootRanges)) {
-					const firstRootRange = rootRanges[0];
-					const rootsForRevision: EncodedRootsForRevision = [
-						encodedRevision,
-						firstRootRange[0],
-						firstRootRange[1],
-					];
-					rootsForRevisions.push(rootsForRevision);
-				} else {
-					const rootsForRevision: EncodedRootsForRevision = [encodedRevision, rootRanges];
-					rootsForRevisions.push(rootsForRevision);
-				}
-			}
-			const encoded: Format = {
-				version,
-				data: rootsForRevisions,
-				maxId: data.maxId,
-			};
-			return encoded;
-		},
-		decode: (parsed: Format): DetachedFieldSummaryData => {
-			const map = new Map();
-			for (const rootsForRevision of parsed.data) {
-				const innerMap = new Map<number, DetachedField>();
-				if (rootsForRevision.length === 2) {
-					for (const [minor, root] of rootsForRevision[1]) {
-						innerMap.set(minor, { root });
-					}
-				} else {
-					innerMap.set(rootsForRevision[1], { root: rootsForRevision[2] });
-				}
-				map.set(majorCodec.decode(rootsForRevision[0]), innerMap);
-			}
-			return {
-				data: map,
-				maxId: parsed.maxId,
-			};
-		},
-	});
+	return makeDetachedFieldIndexCodecFromMajorCodec(
+		options,
+		majorCodec,
+		version1,
+		RevisionTagSchema,
+	);
 }

package/src/core/tree/detachedFieldIndexCodecV2.ts

@@ -0,0 +1,72 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+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 { DetachedFieldSummaryData, Major } from "./detachedFieldIndexTypes.js";
+import { makeDetachedFieldIndexCodecFromMajorCodec } from "./detachedFieldIndexCodecCommon.js";
+import { isStableId } from "@fluidframework/id-compressor/internal";
+
+class MajorCodec implements IJsonCodec<Major> {
+	public constructor(
+		private readonly revisionTagCodec: RevisionTagCodec,
+		private readonly options: ICodecOptions,
+		private readonly idCompressor: IIdCompressor,
+	) {}
+
+	public encode(major: Major): EncodedRevisionTag | StableId {
+		assert(major !== undefined, 0xbfb /* Unexpected undefined revision */);
+		const id = this.revisionTagCodec.encode(major);
+
+		if (id !== "root" && id < 0) {
+			/**
+			 * This code path handles the case where the major revision is not finalized.
+			 * This can happen the SharedTree is being attached to an already attached container.
+			 */
+			assert(major !== "root", 0xbfc /* Major revision cannot be 'root' */);
+			const long = this.idCompressor.decompress(major);
+			return long;
+		}
+		return id;
+	}
+
+	public decode(major: EncodedRevisionTag | StableId): RevisionTag {
+		assert(
+			major === "root" || (typeof major === "string" && isStableId(major)) || major >= 0,
+			0xbfd /* Expected root, stable, or final compressed id */,
+		);
+		if (typeof major === "string" && isStableId(major)) {
+			return this.idCompressor.recompress(major);
+		}
+		return this.revisionTagCodec.decode(major, {
+			originatorId: this.revisionTagCodec.localSessionId,
+			idCompressor: this.idCompressor,
+			revision: undefined,
+		});
+	}
+}
+
+export function makeDetachedNodeToFieldCodecV2(
+	revisionTagCodec: RevisionTagCodec,
+	options: ICodecOptions,
+	idCompressor: IIdCompressor,
+): IJsonCodec<DetachedFieldSummaryData, FormatV2> {
+	const majorCodec = new MajorCodec(revisionTagCodec, options, idCompressor);
+	return makeDetachedFieldIndexCodecFromMajorCodec(
+		options,
+		majorCodec,
+		version2,
+		StableOrFinalRevisionTag,
+	);
+}

package/src/core/tree/detachedFieldIndexCodecs.ts

@@ -0,0 +1,44 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IIdCompressor } from "@fluidframework/id-compressor";
+
+import {
+	type CodecWriteOptions,
+	FluidClientVersion,
+	type ICodecFamily,
+	type IJsonCodec,
+	makeCodecFamily,
+	makeVersionDispatchingCodec,
+} 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";
+
+export function makeDetachedFieldIndexCodec(
+	revisionTagCodec: RevisionTagCodec,
+	options: CodecWriteOptions,
+	idCompressor: IIdCompressor,
+): IJsonCodec<DetachedFieldSummaryData> {
+	const family = makeDetachedFieldIndexCodecFamily(revisionTagCodec, options, idCompressor);
+	const writeVersion =
+		options.oldestCompatibleClient < FluidClientVersion.v2_52 ? version1 : version2;
+	return makeVersionDispatchingCodec(family, { ...options, writeVersion });
+}
+
+export function makeDetachedFieldIndexCodecFamily(
+	revisionTagCodec: RevisionTagCodec,
+	options: CodecWriteOptions,
+	idCompressor: IIdCompressor,
+): ICodecFamily<DetachedFieldSummaryData> {
+	return makeCodecFamily([
+		[version1, makeDetachedNodeToFieldCodecV1(revisionTagCodec, options, idCompressor)],
+		[version2, makeDetachedNodeToFieldCodecV2(revisionTagCodec, options, idCompressor)],
+	]);
+}

package/src/core/tree/{detachedFieldIndexFormat.ts → detachedFieldIndexFormatCommon.ts}

@@ -3,15 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { type Static, Type } from "@sinclair/typebox";
+import { type Static, type TSchema, Type } from "@sinclair/typebox";
 
 import { brandedNumberType } from "../../util/index.js";
-import { RevisionTagSchema } from "../rebase/index.js";
 
 import type { ForestRootId } from "./detachedFieldIndexTypes.js";
 
-export const version = 1.0;
-
 /**
  * The ID of a detached node. Is not globally unique on.
  * A `RevisionTag` + `DetachId` pair is globally unique and eventually consistent across clients.
@@ -22,7 +19,10 @@ export const DetachId = Type.Number({ multipleOf: 1 });
  * The ID of a root node in the forest associated with the owning checkout. Is unique for that forest.
  * Is not consistent across clients.
  */
-const ForestRootIdSchema = brandedNumberType<ForestRootId>({ minimum: -1, multipleOf: 1 });
+export const ForestRootIdSchema = brandedNumberType<ForestRootId>({
+	minimum: -1,
+	multipleOf: 1,
+});
 
 /**
  * A mapping from a range of the detached node IDs the corresponding range root IDs.
@@ -43,21 +43,30 @@ export type RootRanges = Static<typeof RootRanges>;
 /**
  * For all the roots detached in a revision, represents a mapping from the detached node ID to corresponding root ID.
  */
-export const EncodedRootsForRevision = Type.Union([
-	// Used to represent a revision in which more than one node were detached
-	Type.Tuple([RevisionTagSchema, RootRanges]),
-	// Used to represent a revision in which a single node was detached
-	Type.Tuple([RevisionTagSchema, DetachId, ForestRootIdSchema]),
-]);
-export type EncodedRootsForRevision = Static<typeof EncodedRootsForRevision>;
-
-export const Format = Type.Object(
-	{
-		version: Type.Literal(version),
-		data: Type.Array(EncodedRootsForRevision),
-		maxId: ForestRootIdSchema,
-	},
-	{ additionalProperties: false },
-);
-
-export type Format = Static<typeof Format>;
+// Return type is intentionally derived.
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export const EncodedRootsForRevision = <Schema extends TSchema>(tRevisionTag: Schema) =>
+	Type.Union([
+		// Used to represent a revision in which more than one node were detached
+		Type.Tuple([tRevisionTag, RootRanges]),
+		// Used to represent a revision in which a single node was detached
+		Type.Tuple([tRevisionTag, DetachId, ForestRootIdSchema]),
+	]);
+export type EncodedRootsForRevision = Static<ReturnType<typeof EncodedRootsForRevision>>;
+
+export const Format = <TVersion extends number, TRevisionTagSchema extends TSchema>(
+	tVersion: TVersion,
+	tRevisionTag: TRevisionTagSchema,
+	// Return type is intentionally derived.
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+) =>
+	Type.Object(
+		{
+			version: Type.Literal(tVersion),
+			data: Type.Array(EncodedRootsForRevision(tRevisionTag)),
+			maxId: ForestRootIdSchema,
+		},
+		{ additionalProperties: false },
+	);
+
+export type Format = Static<ReturnType<typeof Format>>;

package/src/core/tree/detachedFieldIndexFormatV1.ts

@@ -0,0 +1,15 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { Static } from "@sinclair/typebox";
+
+import { Format } from "./detachedFieldIndexFormatCommon.js";
+import { RevisionTagSchema } from "../rebase/index.js";
+
+export const version1 = 1.0;
+
+export const FormatV1 = Format(version1, RevisionTagSchema);
+
+export type FormatV1 = Static<typeof FormatV1>;

package/src/core/tree/detachedFieldIndexFormatV2.ts

@@ -0,0 +1,17 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+
+import { Format } from "./detachedFieldIndexFormatCommon.js";
+import { RevisionTagSchema, StableIdSchema } from "../rebase/index.js";
+
+export const version2 = 2.0;
+
+export const StableOrFinalRevisionTag = Type.Union([RevisionTagSchema, StableIdSchema]);
+
+export const FormatV2 = Format(version2, StableOrFinalRevisionTag);
+
+export type FormatV2 = Static<typeof FormatV2>;