@fluidframework/tree 2.72.0 → 2.73.0

package/package.json

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

package/src/api.ts

@@ -3,19 +3,18 @@
  * Licensed under the MIT License.
  */
 
-import {
-	type TreeView,
-	type TreeViewAlpha,
-	type TreeViewBeta,
-	type ImplicitFieldSchema,
-	// eslint-disable-next-line import-x/no-deprecated
-	asTreeViewAlpha,
+import type {
+	TreeView,
+	TreeViewAlpha,
+	TreeViewBeta,
+	ImplicitFieldSchema,
+	TreeViewConfiguration,
+	TreeViewConfigurationAlpha,
 } from "./simple-tree/index.js";
 
 /**
  * Module entry points for retrieving alternate (alpha/beta) versions of tree APIs.
  * For each API (usually a class) that has an alpha/beta version, add overloads to the function(s) below.
- * In the future, `asBeta` may be added here too.
  * These functions should only be used by external consumers, not referenced internally within the tree package, to avoid circular import dependencies.
  */
 
@@ -25,9 +24,21 @@ import {
  */
 export function asAlpha<TSchema extends ImplicitFieldSchema>(
 	view: TreeView<TSchema>,
-): TreeViewAlpha<TSchema> {
-	// eslint-disable-next-line import-x/no-deprecated
-	return asTreeViewAlpha(view);
+): TreeViewAlpha<TSchema>;
+
+/**
+ * Retrieve the {@link TreeViewConfigurationAlpha | alpha API} for a {@link TreeViewConfiguration}.
+ * @alpha
+ */
+export function asAlpha<TSchema extends ImplicitFieldSchema>(
+	view: TreeViewConfiguration<TSchema>,
+): TreeViewConfigurationAlpha<TSchema>;
+
+/**
+ * Implementation of overloads for {@link asAlpha}.
+ */
+export function asAlpha(view: unknown): unknown {
+	return view;
 }
 
 /**

package/src/codec/codec.ts

@@ -501,7 +501,7 @@ export const FluidClientVersion = {
 
 	/**
 	 * Fluid Framework Client 2.43 and newer.
-	 *
+	 * @remarks
 	 * New formats introduced in 2.43:
 	 * - SchemaFormatVersion.v2
 	 * - MessageFormatVersion.v4
@@ -512,11 +512,19 @@ export const FluidClientVersion = {
 
 	/**
 	 * Fluid Framework Client 2.52 and newer.
-	 *
+	 * @remarks
 	 * New formats introduced in 2.52:
 	 * - DetachedFieldIndexFormatVersion.v2
 	 */
 	v2_52: "2.52.0",
+
+	/**
+	 * Fluid Framework Client 2.73 and newer.
+	 * @remarks
+	 * New formats introduced in 2.73:
+	 * - FieldBatchFormatVersion v2
+	 */
+	v2_73: "2.73.0",
 } as const satisfies Record<string, MinimumVersionForCollab>;
 
 /**

package/src/codec/index.ts

@@ -39,4 +39,5 @@ export {
 	makeVersionedCodec,
 	makeVersionedValidatedCodec,
 	makeVersionDispatchingCodec,
+	makeDiscontinuedCodecVersion,
 } from "./versioned/index.js";

package/src/codec/versioned/codec.ts

@@ -5,7 +5,8 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import type { TSchema } from "@sinclair/typebox";
+import type { SemanticVersion } from "@fluidframework/runtime-utils/internal";
+import { Type, type TSchema } from "@sinclair/typebox";
 
 import type { JsonCompatibleReadOnly } from "../../util/index.js";
 import {
@@ -66,7 +67,7 @@ export function makeVersionedValidatedCodec<
 	TContext = void,
 >(
 	options: ICodecOptions,
-	supportedVersions: Set<number>,
+	supportedVersions: Set<FormatVersion>,
 	schema: EncodedSchema,
 	codec: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>,
 ): IJsonCodec<TDecoded, TEncoded, TValidate, TContext> {
@@ -77,6 +78,43 @@ export function makeVersionedValidatedCodec<
 	);
 }
 
+/**
+ * Creates a codec which always throws a UsageError when encoding or decoding, indicating that the format version is discontinued.
+ */
+export function makeDiscontinuedCodecVersion<
+	TDecoded,
+	TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,
+	TContext = unknown,
+>(
+	options: ICodecOptions,
+	discontinuedVersion: FormatVersion,
+	discontinuedSince: SemanticVersion,
+): IJsonCodec<TDecoded, TEncoded, TEncoded, TContext> {
+	const schema = Type.Object(
+		{
+			version:
+				discontinuedVersion === undefined
+					? Type.Undefined()
+					: Type.Literal(discontinuedVersion),
+		},
+		// Using `additionalProperties: true` allows this schema to be used when loading data encoded by older versions even though they contain additional properties.
+		{ additionalProperties: true },
+	);
+	const codec: IJsonCodec<TDecoded, TEncoded, TEncoded, TContext> = {
+		encode: (_: TDecoded): TEncoded => {
+			throw new UsageError(
+				`Cannot encode data to format ${discontinuedVersion}. The codec was discontinued in FF version ${discontinuedSince}.`,
+			);
+		},
+		decode: (data: TEncoded): TDecoded => {
+			throw new UsageError(
+				`Cannot decode data to format ${data.version}. The codec was discontinued in FF version ${discontinuedSince}.`,
+			);
+		},
+	};
+	return makeVersionedValidatedCodec(options, new Set([discontinuedVersion]), schema, codec);
+}
+
 /**
  * Creates a codec which dispatches to the appropriate member of a codec family based on the version of
  * data it encounters.

package/src/codec/versioned/index.ts

@@ -8,4 +8,5 @@ export {
 	makeVersionedCodec,
 	makeVersionedValidatedCodec,
 	makeVersionDispatchingCodec,
+	makeDiscontinuedCodecVersion,
 } from "./codec.js";

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

@@ -91,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;
 }
 

package/src/core/tree/detachedFieldIndexCodecs.ts

@@ -5,6 +5,10 @@
 
 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,
@@ -31,9 +35,12 @@ import { brand } from "../../util/index.js";
 function clientVersionToDetachedFieldVersion(
 	clientVersion: MinimumVersionForCollab,
 ): DetachedFieldIndexFormatVersion {
-	return clientVersion < FluidClientVersion.v2_52
-		? brand(DetachedFieldIndexFormatVersion.v1)
-		: brand(DetachedFieldIndexFormatVersion.v2);
+	return brand(
+		getConfigForMinVersionForCollab(clientVersion, {
+			[lowestMinVersionForCollab]: DetachedFieldIndexFormatVersion.v1,
+			[FluidClientVersion.v2_52]: DetachedFieldIndexFormatVersion.v2,
+		}),
+	);
 }
 
 export function makeDetachedFieldIndexCodec(

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 CodecWriteOptions,
+	FluidClientVersion,
 	type IJsonCodec,
 	makeVersionedValidatedCodec,
 } from "../../../codec/index.js";
@@ -32,11 +37,17 @@ import {
 
 import { decode } from "./chunkDecoding.js";
 import type { FieldBatch } from "./fieldBatch.js";
-import { EncodedFieldBatch, validVersions, 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,11 +130,6 @@ export type FieldBatchCodec = IJsonCodec<
 	FieldBatchEncodingContext
 >;
 
-/**
- * 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.
@@ -131,8 +137,12 @@ export type FieldBatchCodec = IJsonCodec<
 function clientVersionToFieldBatchVersion(
 	clientVersion: MinimumVersionForCollab,
 ): FieldBatchFormatVersion {
-	// Currently, field batch codec only writes in version 1.
-	return brand(FieldBatchFormatVersion.v1);
+	return brand(
+		getConfigForMinVersionForCollab(clientVersion, {
+			[lowestMinVersionForCollab]: FieldBatchFormatVersion.v1,
+			[FluidClientVersion.v2_73]: FieldBatchFormatVersion.v2,
+		}),
+	);
 }
 
 export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec {
@@ -146,8 +156,27 @@ export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec
 		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(
@@ -156,27 +185,31 @@ export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec
 				);
 			}
 			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;

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 {
@@ -57,7 +57,7 @@ export function compressedEncode(
 		anyFieldEncoder.encodeField(cursor, context, buffer);
 		batchBuffer.push(buffer);
 	}
-	return updateShapesAndIdentifiersEncoding(FieldBatchFormatVersion.v1, 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,13 +13,14 @@ import {
 	IdentifierOrIndex,
 	ShapeIndex,
 } from "./formatGeneric.js";
-import type { Brand } from "../../../util/index.js";
+import { brand, type Brand } from "../../../util/index.js";
 
 /**
  * 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],
@@ -28,7 +29,7 @@ export type FieldBatchFormatVersion = Brand<
 
 // Compatible versions used for format/version validation.
 // TODO: A proper version update policy will need to be documented.
-export const validVersions = new Set([FieldBatchFormatVersion.v1]);
+export const validVersions = new Set([...Object.values(FieldBatchFormatVersion)]);
 
 /**
  * Top level length is implied from length of data array.
@@ -217,8 +218,17 @@ export type EncodedNodeShape = Static<typeof EncodedNodeShape>;
 export type EncodedAnyShape = Static<typeof EncodedAnyShape>;
 export type EncodedIncrementalChunkShape = Static<typeof EncodedIncrementalChunkShape>;
 
-export const EncodedFieldBatch = EncodedFieldBatchGeneric(
-	FieldBatchFormatVersion.v1,
+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>;

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

@@ -4,6 +4,7 @@
  */
 
 import { type Static, type TSchema, Type } from "@sinclair/typebox";
+import type { FieldBatchFormatVersion } from "./format.js";
 
 /**
  * Identifier OR Index of an identifier in the identifier list.
@@ -39,11 +40,14 @@ const EncodedFieldBatchBase = Type.Object(
 
 /**
  * Format for encoding a tree chunk.
- * @param version - format version. Must be changed if there is any change to the generic schema, or the `shape` schema.
+ * @param version - format version.
+ * Must be changed if the previously existing decode logic will not correctly handle the new encoding.
+ * If adding a new encoding version which does not use this format,
+ * this parameter should be retyped to be a union of the subset of FieldBatchFormatVersion values which this supports.
  * @param shape - schema for union of shape format, see {@link DiscriminatedUnionDispatcher}.
  */
 export const EncodedFieldBatchGeneric = <TShapeSchema extends TSchema>(
-	version: number,
+	version: FieldBatchFormatVersion,
 	shape: TShapeSchema,
 	// Return type is intentionally derived.
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -62,4 +66,5 @@ export const EncodedFieldBatchGeneric = <TShapeSchema extends TSchema>(
 export interface EncodedFieldBatchGeneric<TEncodedShape>
 	extends Static<typeof EncodedFieldBatchBase> {
 	shapes: TEncodedShape[];
+	version: FieldBatchFormatVersion;
 }

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

@@ -3,10 +3,7 @@
  * Licensed under the MIT License.
  */
 
-export {
-	EncodedFieldBatch,
-	type FieldBatchFormatVersion,
-} from "./format.js";
+export { EncodedFieldBatch, FieldBatchFormatVersion } from "./format.js";
 export type { FieldBatch } from "./fieldBatch.js";
 export {
 	type FieldBatchCodec,