@fluidframework/tree 2.81.1 → 2.82.0

package/src/extensibleSchemaUnion.ts

@@ -0,0 +1,135 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TreeAlpha, Tree } from "./shared-tree/index.js";
+import type {
+	TreeNodeSchema,
+	TreeNodeFromImplicitAllowedTypes,
+	TreeFieldFromImplicitField,
+	ImplicitFieldSchema,
+	InsertableTreeFieldFromImplicitField,
+	SchemaFactoryBeta,
+} from "./simple-tree/index.js";
+import {
+	createCustomizedFluidFrameworkScopedFactory,
+	eraseSchemaDetailsSubclassable,
+	SchemaFactory,
+	TreeBeta,
+} from "./simple-tree/index.js";
+import type { UnionToIntersection } from "./util/index.js";
+
+/**
+ * Utilities for creating extensible schema unions.
+ * @remarks
+ * Use {@link ExtensibleSchemaUnion.extensibleSchemaUnion} to create the union schema.
+ *
+ * Unlike a schema union created using {@link SchemaStaticsBeta.staged | staged} allowed types, this union allows for unknown future types to exist in addition to the known types.
+ * This allows for faster roll-outs of new types without waiting for old clients to be updated to be aware of them.
+ * This does mean however that old clients may see types they do not know about, which are simply exposed as `undefined` children.
+ *
+ * `staged` types are lower overhead, and might gain support for `unknown` types in the future, so prefer them when possible.
+ * This is simply an alternative for when future compatibility with unknown types is required.
+ * It is built on top of the existing {@link ObjectSchemaOptions.allowUnknownOptionalFields | allowUnknownOptionalFields} feature.
+ *
+ * @example
+ * ```typescript
+ * const sf = new SchemaFactoryBeta("extensibleSchemaUnionExample.items");
+ * class ItemA extends sf.object("A", { x: sf.string }) {}
+ * class ItemB extends sf.object("B", { x: sf.number }) {}
+ *
+ * class AnyItem extends ExtensibleSchemaUnion.extensibleSchemaUnion(
+ * 	[ItemA, ItemB], // Future versions may add more members here
+ * 	sf,
+ * 	"ExtensibleUnion",
+ * ) {}
+ * // Instances of the union are created using `create`.
+ * const anyItem = AnyItem.create(new ItemA({ x: "hello" }));
+ * // Reading the content from the union is done via `child`,
+ * // which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.
+ * const childNode: ItemA | ItemB | undefined = anyItem.child;
+ * // To determine which member of the union was present, its schema can be inspected:
+ * const aSchema = Tree.schema(childNode ?? assert.fail("No child"));
+ * assert.equal(aSchema, ItemA);
+ * ```
+ * @alpha
+ */
+export namespace ExtensibleSchemaUnion {
+	/**
+	 * Members for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
+	 * @alpha
+	 */
+	export interface Members<T> {
+		/**
+		 * The child wrapped by this node, which is has one of the type allowed by the union,
+		 * or `undefined` if the type is one which was added to the union by a future version of this schema.
+		 */
+		readonly child: T | undefined;
+	}
+
+	/**
+	 * Statics for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
+	 * @alpha
+	 */
+	export interface Statics<T extends readonly TreeNodeSchema[]> {
+		/**
+		 * Create a {@link TreeNode} with `this` schema which wraps the provided child to create the union.
+		 */
+		create<TThis extends TreeNodeSchema>(
+			this: TThis,
+			child: TreeNodeFromImplicitAllowedTypes<T>,
+		): TreeFieldFromImplicitField<TThis>;
+	}
+
+	/**
+	 * Create an extensible schema union which currently supports the types in `types`,
+	 * but tolerates collaboration with future versions that may include additional types.
+	 * @remarks
+	 * See {@link ExtensibleSchemaUnion} for an example use.
+	 * @alpha
+	 */
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+	export function extensibleSchemaUnion<
+		const T extends readonly TreeNodeSchema[],
+		const TScope extends string,
+		const TName extends string,
+	>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName) {
+		const record: Record<string, ImplicitFieldSchema> = {};
+		for (const type of types) {
+			record[`_${type.identifier}`] = SchemaFactory.optional(type, { key: type.identifier });
+		}
+		const schemaFactory = createCustomizedFluidFrameworkScopedFactory(
+			inputSchemaFactory,
+			"extensibleSchemaUnion",
+		);
+		class Union
+			extends schemaFactory.object(name, record, { allowUnknownOptionalFields: true })
+			implements Members<TreeNodeFromImplicitAllowedTypes<T>>
+		{
+			public get child(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+				for (const [_key, child] of TreeAlpha.children(this)) {
+					return child as TreeNodeFromImplicitAllowedTypes<T>;
+				}
+				return undefined;
+			}
+
+			public static create<TThis extends TreeNodeSchema>(
+				this: TThis,
+				child: TreeNodeFromImplicitAllowedTypes<T>,
+			): TreeFieldFromImplicitField<TThis> {
+				const schema = Tree.schema(child);
+				return TreeBeta.create(this, {
+					[`_${schema.identifier}`]: child,
+				} as unknown as InsertableTreeFieldFromImplicitField<
+					TThis,
+					UnionToIntersection<TThis>
+				>);
+			}
+		}
+		return eraseSchemaDetailsSubclassable<
+			Members<TreeNodeFromImplicitAllowedTypes<T>>,
+			Statics<T>
+		>()(Union);
+	}
+}

package/src/feature-libraries/changeAtomIdBTree.ts

@@ -3,8 +3,14 @@
  * Licensed under the MIT License.
  */
 
-import type { ChangeAtomId, ChangesetLocalId, RevisionTag } from "../core/index.js";
-import type { TupleBTree } from "../util/index.js";
+import {
+	compareChangesetLocalIds,
+	comparePartialRevisions,
+	type ChangeAtomId,
+	type ChangesetLocalId,
+	type RevisionTag,
+} from "../core/index.js";
+import { createTupleComparator, newTupleBTree, type TupleBTree } from "../util/index.js";
 
 /**
  * A BTree which uses ChangeAtomId flattened into a tuple as the key.
@@ -16,6 +22,15 @@ export type ChangeAtomIdBTree<V> = TupleBTree<
 	V
 >;
 
+/** Creates a new {@link ChangeAtomIdBTree} */
+export function newChangeAtomIdBTree<V>(
+	entries?: [readonly [RevisionTag | undefined, ChangesetLocalId], V][],
+): ChangeAtomIdBTree<V> {
+	return newTupleBTree(compareKeys, entries);
+}
+
+const compareKeys = createTupleComparator([comparePartialRevisions, compareChangesetLocalIds]);
+
 export function getFromChangeAtomIdMap<T>(
 	map: ChangeAtomIdBTree<T>,
 	id: ChangeAtomId,

package/src/feature-libraries/default-schema/defaultFieldKinds.ts

@@ -12,7 +12,6 @@ import {
 	forbiddenFieldKindIdentifier,
 	Multiplicity,
 } from "../../core/index.js";
-import { brand, type Brand } from "../../util/index.js";
 import { identifierFieldIdentifier } from "../fieldKindIdentifiers.js";
 import {
 	type FieldChangeDelta,
@@ -22,6 +21,7 @@ import {
 	type FieldKindConfigurationEntry,
 	FlexFieldKind,
 	type FullSchemaPolicy,
+	ModularChangeFormatVersion,
 	type ToDelta,
 	referenceFreeFieldChangeRebaser,
 } from "../modular-schema/index.js";
@@ -107,9 +107,9 @@ export const forbidden: Forbidden = new FlexFieldKind(
 export const fieldKindConfigurations: ReadonlyMap<
 	ModularChangeFormatVersion,
 	FieldKindConfiguration
-> = new Map([
+> = new Map<ModularChangeFormatVersion, FieldKindConfiguration>([
 	[
-		brand(3),
+		ModularChangeFormatVersion.v3,
 		new Map<FieldKindIdentifier, FieldKindConfigurationEntry>([
 			[required.identifier, { kind: required, formatVersion: 2 }],
 			[optional.identifier, { kind: optional, formatVersion: 2 }],
@@ -119,7 +119,7 @@ export const fieldKindConfigurations: ReadonlyMap<
 		]),
 	],
 	[
-		brand(4),
+		ModularChangeFormatVersion.v4,
 		new Map<FieldKindIdentifier, FieldKindConfigurationEntry>([
 			[required.identifier, { kind: required, formatVersion: 2 }],
 			[optional.identifier, { kind: optional, formatVersion: 2 }],
@@ -129,7 +129,7 @@ export const fieldKindConfigurations: ReadonlyMap<
 		]),
 	],
 	[
-		brand(5),
+		ModularChangeFormatVersion.v5,
 		new Map<FieldKindIdentifier, FieldKindConfigurationEntry>([
 			[required.identifier, { kind: required, formatVersion: 2 }],
 			[optional.identifier, { kind: optional, formatVersion: 2 }],
@@ -140,7 +140,6 @@ export const fieldKindConfigurations: ReadonlyMap<
 	],
 ]);
 
-export type ModularChangeFormatVersion = Brand<3 | 4 | 5, "ModularChangeFormatVersion">;
 export function getCodecTreeForModularChangeFormat(
 	version: ModularChangeFormatVersion,
 ): CodecTree {

package/src/feature-libraries/default-schema/index.ts

@@ -8,7 +8,6 @@ export {
 	fieldKinds,
 	fieldKindConfigurations,
 	getCodecTreeForModularChangeFormat,
-	type ModularChangeFormatVersion,
 	defaultSchemaPolicy,
 } from "./defaultFieldKinds.js";
 

package/src/feature-libraries/forest-summary/codec.ts

@@ -18,7 +18,7 @@ import {
 	makeVersionedValidatedCodec,
 } from "../../codec/index.js";
 import type { FieldKey, ITreeCursorSynchronous } from "../../core/index.js";
-import { brand } from "../../util/index.js";
+import { brand, type JsonCompatibleReadOnly } from "../../util/index.js";
 import type { FieldBatchCodec, FieldBatchEncodingContext } from "../chunked-forest/index.js";
 
 import {
@@ -32,7 +32,12 @@ import {
  * Uses field cursors
  */
 export type FieldSet = ReadonlyMap<FieldKey, ITreeCursorSynchronous>;
-export type ForestCodec = IJsonCodec<FieldSet, Format, Format, FieldBatchEncodingContext>;
+export type ForestCodec = IJsonCodec<
+	FieldSet,
+	Format,
+	JsonCompatibleReadOnly,
+	FieldBatchEncodingContext
+>;
 
 /**
  * Convert a MinimumVersionForCollab to a ForestFormatVersion.

package/src/feature-libraries/forest-summary/forestSummarizer.ts

@@ -32,7 +32,11 @@ import {
 	type SummaryElementParser,
 	type SummaryElementStringifier,
 } from "../../shared-tree-core/index.js";
-import { idAllocatorFromMaxId, readAndParseSnapshotBlob } from "../../util/index.js";
+import {
+	idAllocatorFromMaxId,
+	readAndParseSnapshotBlob,
+	type JsonCompatibleReadOnly,
+} from "../../util/index.js";
 // eslint-disable-next-line import-x/no-internal-modules
 import { chunkFieldSingle, defaultChunkPolicy } from "../chunked-forest/chunkTree.js";
 import {
@@ -211,7 +215,12 @@ export class ForestSummarizer
 		// TODO: this code is parsing data without an optional validator, this should be defined in a typebox schema as part of the
 		// forest summary format.
 		const fields = this.codec.decode(
-			await readAndParseSnapshotBlob(forestSummaryRootContentKey, services, parse),
+			(await readAndParseSnapshotBlob(
+				forestSummaryRootContentKey,
+				services,
+				parse,
+				// TODO: this type cast assumes there are no handles, which should probably be enforced at runtime or the need for this cast should be removed altogether.
+			)) as JsonCompatibleReadOnly,
 			{
 				...this.encoderContext,
 				incrementalEncoderDecoder: this.incrementalSummaryBuilder,
@@ -230,7 +239,10 @@ export class ForestSummarizer
 				id: buildId,
 				trees: chunked,
 			});
-			fieldChanges.push([fieldKey, [{ count: chunked.topLevelLength, attach: buildId }]]);
+			fieldChanges.push([
+				fieldKey,
+				{ marks: [{ count: chunked.topLevelLength, attach: buildId }] },
+			]);
 		}
 
 		assert(this.forest.isEmpty, 0x797 /* forest must be empty */);

package/src/feature-libraries/forest-summary/formatCommon.ts

@@ -6,8 +6,7 @@
 import { type Static, Type } from "@sinclair/typebox";
 
 import { schemaFormatV1 } from "../../core/index.js";
-import { strictEnum, type Values } from "../../util/index.js";
-import { EncodedFieldBatch } from "../chunked-forest/index.js";
+import { strictEnum, type Values, JsonCompatibleReadOnlySchema } from "../../util/index.js";
 
 /**
  * The format version for the forest.
@@ -30,7 +29,7 @@ export const FormatCommon = (
 		{
 			version: Type.Literal(version),
 			keys: Type.Array(schemaFormatV1.FieldKeySchema),
-			fields: EncodedFieldBatch,
+			fields: JsonCompatibleReadOnlySchema, // Uses field batch codec
 		},
 		{ additionalProperties: false },
 	);

package/src/feature-libraries/forest-summary/incrementalSummaryBuilder.ts

@@ -276,9 +276,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 	 */
 	public async load(args: {
 		services: IChannelStorageService;
-		readAndParseChunk: <T extends JsonCompatible<IFluidHandle>>(
-			chunkBlobPath: string,
-		) => Promise<T>;
+		readAndParseChunk: (chunkBlobPath: string) => Promise<JsonCompatible<IFluidHandle>>;
 	}): Promise<void> {
 		const forestTree = args.services.getSnapshotTree?.();
 		// Snapshot tree should be available when loading forest's contents. However, it is an optional function
@@ -303,8 +301,9 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 						`SharedTree: Cannot find contents for incremental chunk ${chunkContentsPath}`,
 					);
 				}
-				const chunkContents =
-					await args.readAndParseChunk<EncodedFieldBatch>(chunkContentsPath);
+				const chunkContents = (await args.readAndParseChunk(
+					chunkContentsPath,
+				)) as EncodedFieldBatch; // TODO: this should use a codec to validate the data instead of just type casting.
 				this.loadedChunksMap.set(chunkReferenceId, {
 					encodedContents: chunkContents,
 					summaryPath: chunkSubTreePath,

package/src/feature-libraries/index.ts

@@ -48,8 +48,8 @@ export {
 	jsonableTreeFromForest,
 } from "./treeTextCursor.js";
 
-// Split this up into separate import and export for compatibility with API-Extractor.
 import * as SequenceField from "./sequence-field/index.js";
+// eslint-disable-next-line unicorn/prefer-export-from -- fixing requires `export * as` (breaks API-Extractor) or named exports (changes public API)
 export { SequenceField };
 
 export {
@@ -89,6 +89,7 @@ export {
 	type FieldKindConfigurationEntry,
 	isNeverTree,
 	DefaultRevisionReplacer,
+	ModularChangeFormatVersion,
 } from "./modular-schema/index.js";
 
 export { mapRootChanges } from "./deltaUtils.js";
@@ -139,7 +140,6 @@ export {
 	intoDelta,
 	relevantRemovedRoots,
 	getCodecTreeForModularChangeFormat,
-	type ModularChangeFormatVersion,
 } from "./default-schema/index.js";
 
 export {
@@ -210,6 +210,7 @@ export {
 
 export {
 	type ChangeAtomIdBTree,
+	newChangeAtomIdBTree,
 	getFromChangeAtomIdMap,
 	setInChangeAtomIdMap,
 } from "./changeAtomIdBTree.js";

package/src/feature-libraries/modular-schema/defaultRevisionReplacer.ts

@@ -3,28 +3,38 @@
  * Licensed under the MIT License.
  */
 
-import type {
-	ChangeAtomId,
-	ChangesetLocalId,
-	RevisionReplacer,
-	RevisionTag,
+import { assert, fail } from "@fluidframework/core-utils/internal";
+
+import {
+	newChangeAtomIdRangeMap,
+	offsetChangeAtomId,
+	type ChangeAtomId,
+	type ChangeAtomIdRangeMap,
+	type ChangesetLocalId,
+	type RevisionReplacer,
+	type RevisionTag,
 } from "../../core/index.js";
-import { brand, brandConst, newTupleBTree, type Mutable } from "../../util/index.js";
 import {
-	getFromChangeAtomIdMap,
-	setInChangeAtomIdMap,
-	type ChangeAtomIdBTree,
-} from "../changeAtomIdBTree.js";
+	brand,
+	brandConst,
+	newIntegerRangeMap,
+	type RangeMap,
+	type Mutable,
+} from "../../util/index.js";
+
+const offsetChangesetLocalId = (value: ChangesetLocalId, offset: number): ChangesetLocalId =>
+	brand(value + offset);
 
 export class DefaultRevisionReplacer implements RevisionReplacer {
 	/**
 	 * Mapping from (obsolete revision tag, original local id) to the updated local id.
 	 */
-	private readonly updatedLocalIds: ChangeAtomIdBTree<ChangesetLocalId> = newTupleBTree();
+	private readonly updatedLocalIds: ChangeAtomIdRangeMap<ChangesetLocalId> =
+		newChangeAtomIdRangeMap(offsetChangesetLocalId);
 	/**
 	 * The set of local IDs already used in the scope of the updated revision.
 	 */
-	private readonly localIds: Set<ChangesetLocalId> = new Set();
+	private readonly localIds: RangeMap<ChangesetLocalId, true> = newIntegerRangeMap();
 	/**
 	 * The maximum local ID seen so far in the scope of the updated revision.
 	 */
@@ -39,29 +49,45 @@ export class DefaultRevisionReplacer implements RevisionReplacer {
 		return this.obsoleteRevisions.has(revision);
 	}
 
-	public getUpdatedAtomId<T extends ChangeAtomId>(id: T): T {
+	public getUpdatedAtomId<T extends ChangeAtomId>(id: T, count: number = 1): T {
+		assert(count >= 1, 0xcc9 /* Count must be at least 1 */);
 		if (this.isObsolete(id.revision)) {
 			const updated: Mutable<T> = { ...id, revision: this.updatedRevision };
-			const prior: ChangesetLocalId | undefined = getFromChangeAtomIdMap(
-				this.updatedLocalIds,
-				id,
-			);
-			if (prior === undefined) {
-				let localId: ChangesetLocalId;
-				if (this.localIds.has(id.localId)) {
-					this.maxSeen = brand(this.maxSeen + 1);
-					localId = this.maxSeen;
+			let continuingOutputId: ChangesetLocalId | undefined;
+			let remainderCount = count;
+			let remainderStart = id;
+			while (remainderCount > 0) {
+				const prior = this.updatedLocalIds.getFirst(remainderStart, remainderCount);
+				if (prior.value === undefined) {
+					const defaultOutputId = continuingOutputId ?? remainderStart.localId;
+					const newLocalId =
+						this.localIds.getAll(defaultOutputId, prior.length).length > 0
+							? // Some of the IDs in this range have already been used in the scope of the updated revision.
+								// We need to allocate new local IDs.
+								brand<ChangesetLocalId>(this.maxSeen + 1)
+							: // This change atom ID uses a local ID that has not yet been used in the scope of the updated revision.
+								// We reuse it as is to minimize the number of IDs that need to be updated.
+								defaultOutputId;
+
+					this.maxSeen = brand(Math.max(this.maxSeen, newLocalId + prior.length - 1));
+					this.localIds.set(newLocalId, prior.length, true);
+					this.updatedLocalIds.set(remainderStart, prior.length, newLocalId);
+					if (continuingOutputId === undefined) {
+						updated.localId = newLocalId;
+					} else if (newLocalId !== continuingOutputId) {
+						fail(0xcca /* TODO: Handle non-contiguous ranges */);
+					}
+					continuingOutputId = offsetChangesetLocalId(newLocalId, prior.length);
 				} else {
-					// This change atom ID uses a local ID that has not yet been used in the scope of the updated revision.
-					// We reuse it as is to minimize the number of IDs that need to be updated.
-					localId = id.localId;
-					this.maxSeen = brand(Math.max(this.maxSeen, localId));
-					this.localIds.add(id.localId);
+					if (continuingOutputId === undefined) {
+						updated.localId = prior.value;
+					} else if (prior.value !== continuingOutputId) {
+						fail(0xccb /* TODO: Handle non-contiguous ranges */);
+					}
+					continuingOutputId = offsetChangesetLocalId(prior.value, prior.length);
 				}
-				setInChangeAtomIdMap(this.updatedLocalIds, id, localId);
-				updated.localId = localId;
-			} else {
-				updated.localId = prior;
+				remainderStart = offsetChangeAtomId(remainderStart, prior.length);
+				remainderCount -= prior.length;
 			}
 			return updated;
 		}

package/src/feature-libraries/modular-schema/genericFieldKind.ts

@@ -60,7 +60,7 @@ export const genericChangeHandler: FieldChangeHandler<GenericChangeset> = {
 			markList.push({ count: 1, fields: deltaFromChild(nodeChange) });
 			nodeIndex += 1;
 		}
-		return { local: markList };
+		return { local: { marks: markList } };
 	},
 	relevantRemovedRoots,
 	isEmpty: (change: GenericChangeset): boolean => change.length === 0,

package/src/feature-libraries/modular-schema/index.ts

@@ -74,7 +74,10 @@ export {
 	relevantRemovedRoots,
 	updateRefreshers,
 } from "./modularChangeFamily.js";
-export { makeModularChangeCodecFamily } from "./modularChangeCodecs.js";
+export {
+	ModularChangeFormatVersion,
+	makeModularChangeCodecFamily,
+} from "./modularChangeCodecs.js";
 export type {
 	FieldKindConfiguration,
 	FieldKindConfigurationEntry,

package/src/feature-libraries/modular-schema/modularChangeCodecV1.ts

@@ -30,9 +30,8 @@ import {
 	type Mutable,
 	brand,
 	idAllocatorFromMaxId,
-	newTupleBTree,
 } from "../../util/index.js";
-import type { ChangeAtomIdBTree } from "../changeAtomIdBTree.js";
+import { newChangeAtomIdBTree, type ChangeAtomIdBTree } from "../changeAtomIdBTree.js";
 import {
 	type FieldBatchCodec,
 	type TreeChunk,
@@ -364,7 +363,7 @@ export function decodeDetachedNodes(
 		});
 	};
 
-	const map: ModularChangeset["builds"] = newTupleBTree();
+	const map: ModularChangeset["builds"] = newChangeAtomIdBTree();
 	// eslint-disable-next-line unicorn/no-array-for-each -- Codec internals: minimizing changes to serialization logic
 	encoded.builds.forEach((build) => {
 		// EncodedRevisionTag cannot be an array so this ensures that we can isolate the tuple
@@ -396,7 +395,9 @@ export function encodeRevisionInfos(
 ): EncodedRevisionInfo[] | undefined {
 	if (context.revision !== undefined) {
 		assert(
+			// eslint-disable-next-line @typescript-eslint/prefer-optional-chain -- Using optional chaining here would change behavior: `revisions[0]?.rollbackOf === undefined` is true when revisions[0] is undefined, but this check requires revisions[0] to be defined. As currently written, such a change would be safe because context.revision is included in the check and from a couple lines above is confirmed not undefined. But this more verbose form is clearer.
 			revisions.length === 1 &&
+				// eslint-disable-next-line @typescript-eslint/prefer-optional-chain
 				revisions[0] !== undefined &&
 				revisions[0].revision === context.revision &&
 				revisions[0].rollbackOf === undefined,
@@ -525,9 +526,9 @@ export function decodeChange(
 ): Mutable<ModularChangeset> {
 	const decoded: Mutable<ModularChangeset> = {
 		fieldChanges: new Map(),
-		nodeChanges: newTupleBTree(),
-		nodeToParent: newTupleBTree(),
-		nodeAliases: newTupleBTree(),
+		nodeChanges: newChangeAtomIdBTree(),
+		nodeToParent: newChangeAtomIdBTree(),
+		nodeAliases: newChangeAtomIdBTree(),
 		crossFieldKeys: newCrossFieldKeyTable(),
 	};
 

package/src/feature-libraries/modular-schema/modularChangeCodecs.ts

@@ -16,6 +16,7 @@ import type {
 	EncodedRevisionTag,
 	RevisionTag,
 } from "../../core/index.js";
+import { strictEnum, type Values } from "../../util/index.js";
 import type { FieldBatchCodec } from "../chunked-forest/index.js";
 import { TreeCompressionStrategy } from "../treeCompressionUtils.js";
 
@@ -25,7 +26,7 @@ import { makeModularChangeCodecV2 } from "./modularChangeCodecV2.js";
 import type { ModularChangeset } from "./modularChangeTypes.js";
 
 export function makeModularChangeCodecFamily(
-	fieldKindConfigurations: ReadonlyMap<number, FieldKindConfiguration>,
+	fieldKindConfigurations: ReadonlyMap<ModularChangeFormatVersion, FieldKindConfiguration>,
 	revisionTagCodec: IJsonCodec<
 		RevisionTag,
 		EncodedRevisionTag,
@@ -39,11 +40,8 @@ export function makeModularChangeCodecFamily(
 	return makeCodecFamily(
 		Array.from(fieldKindConfigurations.entries(), ([version, fieldKinds]) => {
 			switch (version) {
-				case 1:
-				case 2:
-				case 3:
-				case 4:
-				case 6: {
+				case ModularChangeFormatVersion.v3:
+				case ModularChangeFormatVersion.v4: {
 					return [
 						version,
 						makeModularChangeCodecV1(
@@ -55,7 +53,7 @@ export function makeModularChangeCodecFamily(
 						),
 					];
 				}
-				case 5: {
+				case ModularChangeFormatVersion.v5: {
 					return [
 						version,
 						makeModularChangeCodecV2(
@@ -74,3 +72,30 @@ export function makeModularChangeCodecFamily(
 		}),
 	);
 }
+
+/**
+ * The format version for `ModularChangeset`.
+ */
+export const ModularChangeFormatVersion = strictEnum("ModularChangeFormatVersion", {
+	/**
+	 * Introduced prior to 2.0 and used beyond.
+	 * Reading capability must be maintained for backwards compatibility.
+	 * Writing capability needs to be maintained so long as {@link lowestMinVersionForCollab} is less than 2.2.0.
+	 */
+	v3: 3,
+	/**
+	 * Introduced in 2.2.0.
+	 * Was inadvertently made usable for writing in 2.43.0 (through configuredSharedTree) and remains available.
+	 * Reading capability must be maintained for backwards compatibility.
+	 * Writing capability could be dropped in favor of {@link ModularChangeFormatVersion.v3},
+	 * but doing so would make the pattern of writable versions more complex and gain little
+	 * because the logic for this format is shared with {@link ModularChangeFormatVersion.v3}.
+	 */
+	v4: 4,
+	/**
+	 * Introduced and made available for writing in 2.80.0
+	 * Adds support for "no change" constraints.
+	 */
+	v5: 5,
+});
+export type ModularChangeFormatVersion = Values<typeof ModularChangeFormatVersion>;