@fluidframework/tree 2.71.0 → 2.73.0

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

@@ -10,7 +10,7 @@ import {
 	type Brand,
 	type JsonCompatibleReadOnlyObject,
 	type MakeNominal,
-	brand,
+	brandConst,
 	invertMap,
 } from "../../util/index.js";
 
@@ -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;
 
@@ -88,13 +91,24 @@ export enum ValueSchema {
 export type TreeTypeSet = ReadonlySet<TreeNodeSchemaIdentifier>;
 
 /**
- * Declarative portion of a Field Kind.
+ * Declarative portion of a {@link FlexFieldKind}.
  *
  * @remarks
  * Enough info about a field kind to know if a given tree is is schema.
+ *
+ * Note that compatibility between trees and schema is not sufficient to evaluate if a schema upgrade should be allowed.
+ * Currently schema upgrades are restricted to field kind changes which can not be cyclic (like version upgrades but not down grades).
+ * See {@link FlexFieldKind.allowsFieldSuperset} for more details.
  */
 export interface FieldKindData {
+	/**
+	 * Globally scoped identifier.
+	 */
 	readonly identifier: FieldKindIdentifier;
+	/**
+	 * Bound on the number of children that fields of this kind may have.
+	 * TODO: consider replacing this with numeric upper and lower bounds.
+	 */
 	readonly multiplicity: Multiplicity;
 }
 
@@ -157,7 +171,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: FieldKindIdentifier = brand("Forbidden");
+export const forbiddenFieldKindIdentifier = brandConst("Forbidden")<FieldKindIdentifier>();
 
 /**
  * A schema for empty fields (fields which must always be empty).

package/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>,

package/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,
 	);
 }

package/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,
 	);
 }

package/src/core/tree/detachedFieldIndexCodecs.ts

@@ -4,6 +4,11 @@
  */
 
 import type { IIdCompressor } from "@fluidframework/id-compressor";
+import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+import {
+	getConfigForMinVersionForCollab,
+	lowestMinVersionForCollab,
+} from "@fluidframework/runtime-utils/internal";
 
 import {
 	type CodecTree,
@@ -16,12 +21,27 @@ 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 brand(
+		getConfigForMinVersionForCollab(clientVersion, {
+			[lowestMinVersionForCollab]: DetachedFieldIndexFormatVersion.v1,
+			[FluidClientVersion.v2_52]: DetachedFieldIndexFormatVersion.v2,
+		}),
+	);
+}
 
 export function makeDetachedFieldIndexCodec(
 	revisionTagCodec: RevisionTagCodec,
@@ -29,9 +49,10 @@ export function makeDetachedFieldIndexCodec(
 	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 +61,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),
+	};
 }

package/src/core/tree/detachedFieldIndexFormatCommon.ts

@@ -5,10 +5,22 @@
 
 import { type Static, type TSchema, Type } from "@sinclair/typebox";
 
-import { brandedNumberType } from "../../util/index.js";
+import { brandedNumberType, type Brand } from "../../util/index.js";
 
 import type { ForestRootId } from "./detachedFieldIndexTypes.js";
 
+/**
+ * The format version for the detached field index.
+ */
+export const DetachedFieldIndexFormatVersion = {
+	v1: 1,
+	v2: 2,
+} as const;
+export type DetachedFieldIndexFormatVersion = Brand<
+	(typeof DetachedFieldIndexFormatVersion)[keyof typeof DetachedFieldIndexFormatVersion],
+	"DetachedFieldIndexFormatVersion"
+>;
+
 /**
  * The ID of a detached node. Is not globally unique on.
  * A `RevisionTag` + `DetachId` pair is globally unique and eventually consistent across clients.
@@ -54,7 +66,10 @@ export const EncodedRootsForRevision = <Schema extends TSchema>(tRevisionTag: Sc
 	]);
 export type EncodedRootsForRevision = Static<ReturnType<typeof EncodedRootsForRevision>>;
 
-export const Format = <TVersion extends number, TRevisionTagSchema extends TSchema>(
+export const Format = <
+	TVersion extends DetachedFieldIndexFormatVersion,
+	TRevisionTagSchema extends TSchema,
+>(
 	tVersion: TVersion,
 	tRevisionTag: TRevisionTagSchema,
 	// Return type is intentionally derived.

package/src/core/tree/detachedFieldIndexFormatV1.ts

@@ -5,11 +5,13 @@
 
 import type { Static } from "@sinclair/typebox";
 
-import { Format } from "./detachedFieldIndexFormatCommon.js";
+import { DetachedFieldIndexFormatVersion, Format } from "./detachedFieldIndexFormatCommon.js";
 import { RevisionTagSchema } from "../rebase/index.js";
+import { brand } from "../../util/index.js";
 
-export const version1 = 1.0;
-
-export const FormatV1 = Format(version1, RevisionTagSchema);
+export const FormatV1 = Format(
+	brand<DetachedFieldIndexFormatVersion>(DetachedFieldIndexFormatVersion.v1),
+	RevisionTagSchema,
+);
 
 export type FormatV1 = Static<typeof FormatV1>;

package/src/core/tree/detachedFieldIndexFormatV2.ts

@@ -5,13 +5,15 @@
 
 import { Type, type Static } from "@sinclair/typebox";
 
-import { Format } from "./detachedFieldIndexFormatCommon.js";
+import { DetachedFieldIndexFormatVersion, Format } from "./detachedFieldIndexFormatCommon.js";
 import { RevisionTagSchema, StableIdSchema } from "../rebase/index.js";
-
-export const version2 = 2.0;
+import { brand } from "../../util/index.js";
 
 export const StableOrFinalRevisionTag = Type.Union([RevisionTagSchema, StableIdSchema]);
 
-export const FormatV2 = Format(version2, StableOrFinalRevisionTag);
+export const FormatV2 = Format(
+	brand<DetachedFieldIndexFormatVersion>(DetachedFieldIndexFormatVersion.v2),
+	StableOrFinalRevisionTag,
+);
 
 export type FormatV2 = Static<typeof FormatV2>;

package/src/core/tree/index.ts

@@ -119,9 +119,7 @@ export {
 
 export { DetachedFieldIndex } from "./detachedFieldIndex.js";
 
-export {
-	type DetachedFieldIndexFormatVersion,
-	getCodecTreeForDetachedFieldIndexFormat,
-} from "./detachedFieldIndexCodecs.js";
+export { getCodecTreeForDetachedFieldIndexFormat } from "./detachedFieldIndexCodecs.js";
+export { type DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
 
 export { type ForestRootId } from "./detachedFieldIndexTypes.js";

package/src/external-utilities/typeboxValidator.ts

@@ -5,7 +5,7 @@
 
 import type { Static, TSchema } from "@sinclair/typebox";
 // This export is documented as supported in typebox's documentation.
-// eslint-disable-next-line import/no-internal-modules
+// eslint-disable-next-line import-x/no-internal-modules
 import { TypeCompiler } from "@sinclair/typebox/compiler";
 
 import { toFormatValidator, type JsonValidator } from "../codec/index.js";

package/src/feature-libraries/README.md

@@ -2,7 +2,7 @@
 
 Libraries which plug into the [Core Libraries](../core/README.md) to provide specializations, either for performance, or compatibility with specific tools or use-cases.
 
-This includes concrete implementations of abstractions used to parameterize `SharedTreeCore` (Like `Index` and `ChangeFamily`), or any other entry points to the `core` libraries] package (like `Forest`).
+This includes concrete implementations of abstractions used to parameterize `SharedTreeCore` (Like `Index` and `ChangeFamily`), or any other entry points to the `core` libraries package (like `Forest`).
 
 `SharedTreeCore` should be usable with alternative versions of anything within this library.
 

package/src/feature-libraries/chunked-forest/chunkTree.ts

@@ -23,9 +23,9 @@ import {
 	type TreeChunk,
 	tryGetChunk,
 	type SchemaAndPolicy,
+	type SchemaPolicy,
 } from "../../core/index.js";
 import { getOrCreate } from "../../util/index.js";
-import type { FullSchemaPolicy } from "../modular-schema/index.js";
 import { isStableNodeIdentifier } from "../node-identifier/index.js";
 
 import { BasicChunk } from "./basicChunk.js";
@@ -44,7 +44,7 @@ export interface Disposable {
  */
 export function makeTreeChunker(
 	schema: TreeStoredSchemaSubscription,
-	policy: FullSchemaPolicy,
+	policy: SchemaPolicy,
 	shouldEncodeIncrementally: IncrementalEncodingPolicy,
 ): IChunker {
 	return new Chunker(
@@ -113,7 +113,7 @@ export class Chunker implements IChunker {
 
 	public constructor(
 		public readonly schema: TreeStoredSchemaSubscription,
-		public readonly policy: FullSchemaPolicy,
+		public readonly policy: SchemaPolicy,
 		public readonly sequenceChunkSplitThreshold: number,
 		public readonly sequenceChunkInlineThreshold: number,
 		public readonly uniformChunkNodeCount: number,

package/src/feature-libraries/chunked-forest/codec/chunkDecoding.ts

@@ -46,6 +46,7 @@ import {
 	type EncodedNestedArrayShape,
 	type EncodedNodeShape,
 	type EncodedValueShape,
+	FieldBatchFormatVersion,
 	SpecialField,
 } from "./format.js";
 import type { IncrementalDecoder } from "./codecs.js";
@@ -246,6 +247,10 @@ export class IncrementalChunkDecoder implements ChunkDecoder {
 		);
 
 		const chunkDecoder = (batch: EncodedFieldBatch): TreeChunk => {
+			assert(
+				batch.version >= FieldBatchFormatVersion.v2,
+				0xc9f /* Unsupported FieldBatchFormatVersion for incremental chunks; must be v2 or higher */,
+			);
 			const context = new DecoderContext(
 				batch.identifiers,
 				batch.shapes,

package/src/feature-libraries/chunked-forest/codec/chunkEncodingGeneric.ts

@@ -15,6 +15,7 @@ import {
 	jsonMinimizingFilter,
 } from "./chunkCodecUtilities.js";
 import type { EncodedFieldBatchGeneric } from "./formatGeneric.js";
+import type { FieldBatchFormatVersion } from "./format.js";
 
 /**
  * An identifier which can be compressed using {@link Counter}.
@@ -51,7 +52,7 @@ export type BufferFormat<TEncodedShape> = (
  * Note that this modifies `buffer` to avoid having to copy it.
  */
 export function updateShapesAndIdentifiersEncoding<TEncodedShape>(
-	version: number,
+	version: FieldBatchFormatVersion,
 	buffer: BufferFormat<TEncodedShape>[],
 	identifierFilter: CounterFilter<string> = jsonMinimizingFilter,
 ): EncodedFieldBatchGeneric<TEncodedShape> {

package/src/feature-libraries/chunked-forest/codec/codecs.ts

@@ -5,10 +5,15 @@
 
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
+import {
+	getConfigForMinVersionForCollab,
+	lowestMinVersionForCollab,
+} from "@fluidframework/runtime-utils/internal";
 
 import {
 	type CodecTree,
-	type ICodecOptions,
+	type CodecWriteOptions,
+	FluidClientVersion,
 	type IJsonCodec,
 	makeVersionedValidatedCodec,
 } from "../../../codec/index.js";
@@ -19,6 +24,7 @@ import {
 	type TreeChunk,
 } from "../../../core/index.js";
 import {
+	brand,
 	brandedNumberType,
 	type Brand,
 	type JsonCompatibleReadOnly,
@@ -31,11 +37,17 @@ import {
 
 import { decode } from "./chunkDecoding.js";
 import type { FieldBatch } from "./fieldBatch.js";
-import { EncodedFieldBatch, validVersions, type FieldBatchFormatVersion } from "./format.js";
-import { schemaCompressedEncode } from "./schemaBasedEncode.js";
-import { uncompressedEncode } from "./uncompressedEncode.js";
+import {
+	type EncodedFieldBatch,
+	validVersions,
+	FieldBatchFormatVersion,
+	EncodedFieldBatchV1,
+	EncodedFieldBatchV2,
+} from "./format.js";
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 import type { IncrementalEncodingPolicy } from "./incrementalEncodingPolicy.js";
+import { uncompressedEncodeV1, uncompressedEncodeV2 } from "./uncompressedEncode.js";
+import { schemaCompressedEncodeV1, schemaCompressedEncodeV2 } from "./schemaBasedEncode.js";
 
 /**
  * Reference ID for a chunk that is incrementally encoded.
@@ -119,21 +131,22 @@ export type FieldBatchCodec = IJsonCodec<
 >;
 
 /**
- * Get the write version for {@link makeFieldBatchCodec} based on the `minVersionForCollab` version.
- * @privateRemarks
- * TODO: makeFieldBatchCodec (and makeVersionDispatchingCodec transitively) should bake in this versionToFormat logic and the resulting codec can then support use with FluidClientVersion directly.
+ * Convert a MinimumVersionForCollab to write version for {@link FieldBatchCodec}.
+ * @param clientVersion - The MinimumVersionForCollab to convert.
  */
-export function fluidVersionToFieldBatchCodecWriteVersion(
-	minVersionForCollab: MinimumVersionForCollab,
-): number {
-	// There is currently on only 1 version.
-	return 1;
+function clientVersionToFieldBatchVersion(
+	clientVersion: MinimumVersionForCollab,
+): FieldBatchFormatVersion {
+	return brand(
+		getConfigForMinVersionForCollab(clientVersion, {
+			[lowestMinVersionForCollab]: FieldBatchFormatVersion.v1,
+			[FluidClientVersion.v2_73]: FieldBatchFormatVersion.v2,
+		}),
+	);
 }
 
-export function makeFieldBatchCodec(
-	options: ICodecOptions,
-	writeVersion: number,
-): FieldBatchCodec {
+export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec {
+	const writeVersion = clientVersionToFieldBatchVersion(options.minVersionForCollab);
 	// Note: it's important that the decode function is schema-agnostic for this strategy/layering to work, since
 	// the schema that an op was encoded in doesn't necessarily match the current schema for the document (e.g. if
 	// decode is being run on a client that just submitted a schema change, but the op is from another client who has
@@ -143,8 +156,27 @@ export function makeFieldBatchCodec(
 		0x935 /* Invalid write version for FieldBatch codec */,
 	);
 
-	// TODO: use makeVersionDispatchingCodec to support adding more versions in the future.
-	return makeVersionedValidatedCodec(options, validVersions, EncodedFieldBatch, {
+	let uncompressedEncodeFn: typeof uncompressedEncodeV1 | typeof uncompressedEncodeV2;
+	let schemaCompressedEncodeFn:
+		| typeof schemaCompressedEncodeV1
+		| typeof schemaCompressedEncodeV2;
+	let encodedFieldBatchType: typeof EncodedFieldBatchV1 | typeof EncodedFieldBatchV2;
+	switch (writeVersion) {
+		case FieldBatchFormatVersion.v1:
+			uncompressedEncodeFn = uncompressedEncodeV1;
+			schemaCompressedEncodeFn = schemaCompressedEncodeV1;
+			encodedFieldBatchType = EncodedFieldBatchV1;
+			break;
+		case FieldBatchFormatVersion.v2:
+			uncompressedEncodeFn = uncompressedEncodeV2;
+			schemaCompressedEncodeFn = schemaCompressedEncodeV2;
+			encodedFieldBatchType = EncodedFieldBatchV2;
+			break;
+		default:
+			unreachableCase(writeVersion);
+	}
+
+	return makeVersionedValidatedCodec(options, validVersions, encodedFieldBatchType, {
 		encode: (data: FieldBatch, context: FieldBatchEncodingContext): EncodedFieldBatch => {
 			for (const cursor of data) {
 				assert(
@@ -153,27 +185,31 @@ export function makeFieldBatchCodec(
 				);
 			}
 			let encoded: EncodedFieldBatch;
+			let incrementalEncoder: IncrementalEncoder | undefined;
 			switch (context.encodeType) {
 				case TreeCompressionStrategy.Uncompressed:
-					encoded = uncompressedEncode(data);
+					encoded = uncompressedEncodeFn(data);
 					break;
 				case TreeCompressionStrategyExtended.CompressedIncremental:
+					assert(
+						writeVersion >= FieldBatchFormatVersion.v2,
+						0xca0 /* Unsupported FieldBatchFormatVersion for incremental encoding; must be v2 or higher */,
+					);
+					// Incremental encoding is only supported for CompressedIncremental.
+					incrementalEncoder = context.incrementalEncoderDecoder;
 				case TreeCompressionStrategy.Compressed:
 					// eslint-disable-next-line unicorn/prefer-ternary
 					if (context.schema !== undefined) {
-						encoded = schemaCompressedEncode(
+						encoded = schemaCompressedEncodeFn(
 							context.schema.schema,
 							context.schema.policy,
 							data,
 							context.idCompressor,
-							// Incremental encoding is only supported for CompressedIncremental.
-							context.encodeType === TreeCompressionStrategyExtended.CompressedIncremental
-								? context.incrementalEncoderDecoder
-								: undefined,
+							incrementalEncoder,
 						);
 					} else {
 						// TODO: consider enabling a somewhat compressed but not schema accelerated encode.
-						encoded = uncompressedEncode(data);
+						encoded = uncompressedEncodeFn(data);
 					}
 
 					break;
@@ -198,6 +234,8 @@ export function makeFieldBatchCodec(
 	});
 }
 
-export function getCodecTreeForFieldBatchFormat(version: FieldBatchFormatVersion): CodecTree {
-	return { name: "FieldBatch", version };
+export function getCodecTreeForFieldBatchFormat(
+	clientVersion: MinimumVersionForCollab,
+): CodecTree {
+	return { name: "FieldBatch", version: clientVersionToFieldBatchVersion(clientVersion) };
 }

package/src/feature-libraries/chunked-forest/codec/compressedEncode.ts

@@ -9,6 +9,7 @@ import type { IIdCompressor } from "@fluidframework/id-compressor";
 import {
 	CursorLocationType,
 	type FieldKey,
+	type FieldKindData,
 	type FieldKindIdentifier,
 	type ITreeCursorSynchronous,
 	type TreeChunk,
@@ -18,7 +19,6 @@ import {
 	forEachNode,
 } from "../../../core/index.js";
 import { getOrCreate } from "../../../util/index.js";
-import type { FlexFieldKind } from "../../modular-schema/index.js";
 
 import type { Counter, DeduplicationTable } from "./chunkCodecUtilities.js";
 import {
@@ -33,8 +33,8 @@ import {
 	type EncodedFieldBatch,
 	type EncodedNestedArrayShape,
 	type EncodedValueShape,
+	FieldBatchFormatVersion,
 	SpecialField,
-	version,
 } from "./format.js";
 import type { IncrementalEncoder } from "./codecs.js";
 
@@ -57,7 +57,7 @@ export function compressedEncode(
 		anyFieldEncoder.encodeField(cursor, context, buffer);
 		batchBuffer.push(buffer);
 	}
-	return updateShapesAndIdentifiersEncoding(version, batchBuffer);
+	return updateShapesAndIdentifiersEncoding(context.version, batchBuffer);
 }
 
 export type BufferFormat = BufferFormatGeneric<EncodedChunkShape>;
@@ -458,6 +458,10 @@ export const incrementalFieldEncoder: FieldEncoder = {
 			context.incrementalEncoder !== undefined,
 			0xc88 /* incremental encoder must be defined to use incrementalFieldEncoder */,
 		);
+		assert(
+			context.version >= FieldBatchFormatVersion.v2,
+			0xca1 /* Unsupported FieldBatchFormatVersion for incremental encoding; must be v2 or higher */,
+		);
 
 		const chunkReferenceIds = context.incrementalEncoder.encodeIncrementalField(
 			cursor,
@@ -519,7 +523,7 @@ export class EncoderContext implements NodeEncodeBuilder, FieldEncodeBuilder {
 	public constructor(
 		private readonly nodeEncoderFromPolicy: NodeEncoderPolicy,
 		private readonly fieldEncoderFromPolicy: FieldEncoderPolicy,
-		public readonly fieldShapes: ReadonlyMap<FieldKindIdentifier, FlexFieldKind>,
+		public readonly fieldShapes: ReadonlyMap<FieldKindIdentifier, FieldKindData>,
 		public readonly idCompressor: IIdCompressor,
 		/**
 		 * To be used to encode incremental chunks, if any.
@@ -527,6 +531,7 @@ export class EncoderContext implements NodeEncodeBuilder, FieldEncodeBuilder {
 		 * See {@link IncrementalEncoder} for more information.
 		 */
 		public readonly incrementalEncoder: IncrementalEncoder | undefined,
+		public readonly version: FieldBatchFormatVersion,
 	) {}
 
 	public nodeEncoderFromSchema(schemaName: TreeNodeSchemaIdentifier): NodeEncoder {

package/src/feature-libraries/chunked-forest/codec/format.ts

@@ -13,14 +13,23 @@ import {
 	IdentifierOrIndex,
 	ShapeIndex,
 } from "./formatGeneric.js";
-import type { Brand } from "../../../util/index.js";
+import { brand, type Brand } from "../../../util/index.js";
 
-export const version = 1;
-export type FieldBatchFormatVersion = Brand<1, "FieldBatchFormatVersion">;
+/**
+ * The format version for the field batch.
+ */
+export const FieldBatchFormatVersion = {
+	v1: 1,
+	v2: 2,
+} as const;
+export type FieldBatchFormatVersion = Brand<
+	(typeof FieldBatchFormatVersion)[keyof typeof FieldBatchFormatVersion],
+	"FieldBatchFormatVersion"
+>;
 
 // Compatible versions used for format/version validation.
 // TODO: A proper version update policy will need to be documented.
-export const validVersions = new Set([version]);
+export const validVersions = new Set([...Object.values(FieldBatchFormatVersion)]);
 
 /**
  * Top level length is implied from length of data array.
@@ -209,5 +218,17 @@ export type EncodedNodeShape = Static<typeof EncodedNodeShape>;
 export type EncodedAnyShape = Static<typeof EncodedAnyShape>;
 export type EncodedIncrementalChunkShape = Static<typeof EncodedIncrementalChunkShape>;
 
-export const EncodedFieldBatch = EncodedFieldBatchGeneric(version, EncodedChunkShape);
+export const EncodedFieldBatchV1 = EncodedFieldBatchGeneric(
+	brand<FieldBatchFormatVersion>(FieldBatchFormatVersion.v1),
+	EncodedChunkShape,
+);
+export type EncodedFieldBatchV1 = Static<typeof EncodedFieldBatchV1>;
+
+export const EncodedFieldBatchV2 = EncodedFieldBatchGeneric(
+	brand<FieldBatchFormatVersion>(FieldBatchFormatVersion.v2),
+	EncodedChunkShape,
+);
+export type EncodedFieldBatchV2 = Static<typeof EncodedFieldBatchV2>;
+
+export const EncodedFieldBatch = Type.Union([EncodedFieldBatchV1, EncodedFieldBatchV2]);
 export type EncodedFieldBatch = Static<typeof EncodedFieldBatch>;