@fluidframework/tree 2.74.0 → 2.80.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.74.0",
+  "version": "2.80.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -101,17 +101,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.74.0",
-    "@fluidframework/container-runtime": "~2.74.0",
-    "@fluidframework/core-interfaces": "~2.74.0",
-    "@fluidframework/core-utils": "~2.74.0",
-    "@fluidframework/datastore-definitions": "~2.74.0",
-    "@fluidframework/driver-definitions": "~2.74.0",
-    "@fluidframework/id-compressor": "~2.74.0",
-    "@fluidframework/runtime-definitions": "~2.74.0",
-    "@fluidframework/runtime-utils": "~2.74.0",
-    "@fluidframework/shared-object-base": "~2.74.0",
-    "@fluidframework/telemetry-utils": "~2.74.0",
+    "@fluid-internal/client-utils": "~2.80.0",
+    "@fluidframework/container-runtime": "~2.80.0",
+    "@fluidframework/core-interfaces": "~2.80.0",
+    "@fluidframework/core-utils": "~2.80.0",
+    "@fluidframework/datastore-definitions": "~2.80.0",
+    "@fluidframework/driver-definitions": "~2.80.0",
+    "@fluidframework/id-compressor": "~2.80.0",
+    "@fluidframework/runtime-definitions": "~2.80.0",
+    "@fluidframework/runtime-utils": "~2.80.0",
+    "@fluidframework/shared-object-base": "~2.80.0",
+    "@fluidframework/telemetry-utils": "~2.80.0",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@types/ungap__structured-clone": "^1.2.0",
@@ -120,42 +120,42 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.17.1",
+    "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.74.0",
-    "@fluid-private/stochastic-test-utils": "~2.74.0",
-    "@fluid-private/test-dds-utils": "~2.74.0",
-    "@fluid-private/test-drivers": "~2.74.0",
+    "@fluid-internal/mocha-test-setup": "~2.80.0",
+    "@fluid-private/stochastic-test-utils": "~2.80.0",
+    "@fluid-private/test-dds-utils": "~2.80.0",
+    "@fluid-private/test-drivers": "~2.80.0",
     "@fluid-tools/benchmark": "^0.51.0",
-    "@fluid-tools/build-cli": "^0.61.0",
+    "@fluid-tools/build-cli": "^0.62.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.61.0",
-    "@fluidframework/container-definitions": "~2.74.0",
-    "@fluidframework/container-loader": "~2.74.0",
-    "@fluidframework/eslint-config-fluid": "~2.74.0",
-    "@fluidframework/test-runtime-utils": "~2.74.0",
-    "@fluidframework/test-utils": "~2.74.0",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.73.0",
+    "@fluidframework/build-tools": "^0.62.0",
+    "@fluidframework/container-definitions": "~2.80.0",
+    "@fluidframework/container-loader": "~2.80.0",
+    "@fluidframework/eslint-config-fluid": "~2.80.0",
+    "@fluidframework/test-runtime-utils": "~2.80.0",
+    "@fluidframework/test-utils": "~2.80.0",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.74.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",
     "@types/mocha": "^10.0.10",
     "@types/node": "^18.19.0",
-    "ajv": "^8.12.0",
+    "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "c8": "^10.1.3",
-    "concurrently": "^8.2.1",
+    "concurrently": "^9.2.1",
     "copyfiles": "^2.4.1",
-    "cross-env": "^7.0.3",
-    "dependency-cruiser": "^17.1.0",
+    "cross-env": "^10.1.0",
+    "dependency-cruiser": "^17.3.2",
     "diff": "^3.5.0",
-    "easy-table": "^1.1.1",
-    "eslint": "~8.57.1",
+    "easy-table": "^1.2.0",
+    "eslint": "~9.39.1",
     "eslint-config-prettier": "~10.1.8",
     "jiti": "^2.6.1",
     "mocha": "^10.8.2",
     "mocha-multi-reporters": "^1.5.1",
-    "rimraf": "^4.4.0",
+    "rimraf": "^6.1.2",
     "typescript": "~5.4.5"
   },
   "fluidBuild": {

package/src/codec/codec.ts

@@ -154,6 +154,18 @@ export interface CodecWriteOptions extends ICodecOptions {
 	 * the data's format should be versioned and if they can't handle the format they should error.
 	 */
 	readonly minVersionForCollab: MinimumVersionForCollab;
+
+	/**
+	 * Overrides the version of the codec to use for encoding.
+	 * @remarks
+	 * Without an override, the selected version will be based on {@link CodecWriteOptions.minVersionForCollab}.
+	 */
+	readonly writeVersionOverrides?: ReadonlyMap<CodecName, FormatVersion>;
+
+	/**
+	 * If true, suppress errors when `writeVersionOverrides` selects a version which may not be compatible with the {@link CodecWriteOptions.minVersionForCollab}.
+	 */
+	readonly allowPossiblyIncompatibleWriteVersionOverrides?: boolean;
 }
 
 /**
@@ -252,13 +264,22 @@ export interface ICodecFamily<TDecoded, TContext = void> {
 
 /**
  * A version stamp for encoded data.
- *
+ * @remarks
  * Strings are used for formats that are not yet officially supported.
  * When such formats become officially supported/stable, they will be switched to using a number.
  * Undefined is tolerated to enable the scenario where data was not initially versioned.
+ * @alpha
  */
 export type FormatVersion = number | string | undefined;
 
+/**
+ * A unique name given to this codec family.
+ * @remarks
+ * This is not persisted: it is only used to specify version overrides and in errors.
+ * @alpha
+ */
+export type CodecName = string;
+
 /**
  * A format version which is dependent on some parent format version.
  */
@@ -374,9 +395,13 @@ function isJsonCodec<TDecoded, TContext>(
  * Constructs a {@link IMultiFormatCodec} from a `IJsonCodec` using a generic binary encoding that simply writes
  * the json representation of the object to a buffer.
  */
-export function withDefaultBinaryEncoding<TDecoded, TContext>(
-	jsonCodec: IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,
-): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
+export function withDefaultBinaryEncoding<
+	TDecoded,
+	TContext,
+	TEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,
+>(
+	jsonCodec: IJsonCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext>,
+): IMultiFormatCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext> {
 	return {
 		json: jsonCodec,
 		binary: new DefaultBinaryCodec(jsonCodec),
@@ -387,11 +412,15 @@ export function withDefaultBinaryEncoding<TDecoded, TContext>(
  * Ensures that the provided single or multi-format codec has a binary encoding.
  * Adapts the json encoding using {@link withDefaultBinaryEncoding} if necessary.
  */
-export function ensureBinaryEncoding<TDecoded, TContext>(
+export function ensureBinaryEncoding<
+	TDecoded,
+	TContext,
+	TEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,
+>(
 	codec:
-		| IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>
-		| IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,
-): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
+		| IMultiFormatCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext>
+		| IJsonCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext>,
+): IMultiFormatCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext> {
 	return isJsonCodec(codec) ? withDefaultBinaryEncoding(codec) : codec;
 }
 
@@ -548,6 +577,17 @@ export const FluidClientVersion = {
 	 * - ForestSummaryFormatVersion.v3 - written when minVersionForCollab \>= 2.74
 	 */
 	v2_74: "2.74.0",
+
+	/**
+	 * Fluid Framework Client 2.80 and newer.
+	 * @remarks
+	 * New formats introduced in 2.80:
+	 * - MessageFormatVersion.v6 - written when minVersionForCollab \>= 2.80
+	 * - EditManagerFormatVersion.v6 - written when minVersionForCollab \>= 2.80
+	 * - SharedTreeChangeFormatVersion.v5 - written when minVersionForCollab \>= 2.80
+	 * - ModularChangeFormatVersion.v5 - written when minVersionForCollab \>= 2.80
+	 */
+	v2_80: "2.80.0",
 } as const satisfies Record<string, MinimumVersionForCollab>;
 
 /**

package/src/codec/index.ts

@@ -28,6 +28,7 @@ export {
 	type CodecTree,
 	jsonableCodecTree,
 	extractJsonValidator,
+	type CodecName,
 } from "./codec.js";
 export {
 	DiscriminatedUnionDispatcher,
@@ -36,8 +37,10 @@ export {
 } from "./discriminatedUnions.js";
 export {
 	Versioned,
-	makeVersionedCodec,
 	makeVersionedValidatedCodec,
 	makeVersionDispatchingCodec,
 	makeDiscontinuedCodecVersion,
+	ClientVersionDispatchingCodecBuilder,
+	type CodecVersion,
+	type CodecAndSchema,
 } from "./versioned/index.js";

package/src/codec/versioned/codec.ts

@@ -5,10 +5,19 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import type { SemanticVersion } from "@fluidframework/runtime-utils/internal";
+import {
+	getConfigForMinVersionForCollabIterable,
+	type ConfigMapEntry,
+	type MinimumMinorSemanticVersion,
+	type SemanticVersion,
+} from "@fluidframework/runtime-utils/internal";
 import { Type, type TSchema } from "@sinclair/typebox";
+import { gt } from "semver-ts";
 
-import type { JsonCompatibleReadOnly } from "../../util/index.js";
+import type {
+	JsonCompatibleReadOnly,
+	JsonCompatibleReadOnlyObject,
+} from "../../util/index.js";
 import {
 	type ICodecFamily,
 	type ICodecOptions,
@@ -16,15 +25,24 @@ import {
 	withSchemaValidation,
 	type FormatVersion,
 	type CodecWriteOptions,
+	type IMultiFormatCodec,
+	type CodecName,
+	ensureBinaryEncoding,
+	type CodecTree,
 } from "../codec.js";
 
 import { Versioned } from "./format.js";
 import { pkgVersion } from "../../packageVersion.js";
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 
-export function makeVersionedCodec<
+/**
+ * Json compatible data with a format version.
+ */
+type VersionedJson = JsonCompatibleReadOnlyObject & Versioned;
+
+function makeVersionedCodec<
 	TDecoded,
-	TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,
+	TEncoded extends Versioned = VersionedJson,
 	TValidate = TEncoded,
 	TContext = void,
 >(
@@ -45,7 +63,7 @@ export function makeVersionedCodec<
 			const versioned = data as Versioned; // Validated by withSchemaValidation
 			if (!supportedVersions.has(versioned.version)) {
 				throw new UsageError(
-					`Unsupported version ${versioned.version} encountered while decoding data. Supported versions for this data are: ${Array.from(supportedVersions).join(", ")}.
+					`Unsupported version ${versioned.version} encountered while decoding data. Supported versions for this data are: ${[...supportedVersions].join(", ")}.
 The client which encoded this data likely specified an "minVersionForCollab" value which corresponds to a version newer than the version of this client ("${pkgVersion}").`,
 				);
 			}
@@ -59,10 +77,13 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 		: withSchemaValidation(Versioned, codec, validator);
 }
 
+/**
+ * TODO: users of this should migrate to {@link ClientVersionDispatchingCodecBuilder}.
+ */
 export function makeVersionedValidatedCodec<
 	EncodedSchema extends TSchema,
 	TDecoded,
-	TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,
+	TEncoded extends Versioned = VersionedJson,
 	TValidate = TEncoded,
 	TContext = void,
 >(
@@ -80,10 +101,13 @@ export function makeVersionedValidatedCodec<
 
 /**
  * Creates a codec which always throws a UsageError when encoding or decoding, indicating that the format version is discontinued.
+ *
+ * TODO: {@link ClientVersionDispatchingCodecBuilder} should get support for extra decode only entries and/or unstable formats (codecs without a minVersionForCollab that will never be selected for write unless overridden).
+ * Once done, users of this should migrate to ClientVersionDispatchingCodecBuilder and this function can be simplified.
  */
 export function makeDiscontinuedCodecVersion<
 	TDecoded,
-	TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,
+	TEncoded extends Versioned = VersionedJson,
 	TContext = unknown,
 >(
 	options: ICodecOptions,
@@ -103,12 +127,12 @@ export function makeDiscontinuedCodecVersion<
 	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}.`,
+				`Cannot encode data to format ${discontinuedVersion}. The codec was discontinued in Fluid Framework client version ${discontinuedSince}.`,
 			);
 		},
 		decode: (data: TEncoded): TDecoded => {
 			throw new UsageError(
-				`Cannot decode data to format ${data.version}. The codec was discontinued in FF version ${discontinuedSince}.`,
+				`Cannot decode data to format ${data.version}. The codec was discontinued in Fluid Framework client version ${discontinuedSince}.`,
 			);
 		},
 	};
@@ -125,7 +149,7 @@ export function makeDiscontinuedCodecVersion<
  */
 export function makeVersionDispatchingCodec<TDecoded, TContext>(
 	family: ICodecFamily<TDecoded, TContext>,
-	options: ICodecOptions & { writeVersion: number | string },
+	options: ICodecOptions & { writeVersion: FormatVersion },
 ): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
 	const writeCodec = family.resolve(options.writeVersion).json;
 	const supportedVersions = new Set(family.getSupportedFormats());
@@ -140,30 +164,324 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
 	});
 }
 
+/**
+ * A friendly format for codec authors use to define their codec and schema for use in {@link CodecVersion}.
+ * @remarks
+ * The codec should not perform its own schema validation.
+ * The schema validation gets added when normalizing to {@link NormalizedCodecVersion}.
+ */
+export type CodecAndSchema<TDecoded, TContext = void> = { readonly schema: TSchema } & (
+	| IMultiFormatCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>
+	| IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>
+);
+
+/**
+ * A codec alongside its format version and schema.
+ */
+export interface CodecVersionBase<
+	T = unknown,
+	TFormatVersion extends FormatVersion = FormatVersion,
+> {
+	readonly formatVersion: TFormatVersion;
+	readonly codec: T;
+}
+
+/**
+ * A particular version of a codec and when to use it.
+ * @privateRemarks
+ * This allows lazy building of the codec with options.
+ * This option can likely be removed as the codec handling is made simpler and more consistent.
+ * Removing support for this laziness would be nice to help prevent unexpected coupling and alteration to codec behavior,
+ * helping ensure that tests and production code behave the same.
+ */
+export interface CodecVersion<
+	TDecoded,
+	TContext,
+	TFormatVersion extends FormatVersion,
+	TBuildOptions extends CodecWriteOptions,
+> extends CodecVersionBase<
+		| CodecAndSchema<TDecoded, TContext>
+		| ((options: TBuildOptions) => CodecAndSchema<TDecoded, TContext>),
+		TFormatVersion
+	> {}
+
+/**
+ * {@link CodecVersion} after normalization into a consistent type.
+ * @remarks
+ * Produced by {@link normalizeCodecVersion}.
+ * Includes schema validation.
+ */
+export interface NormalizedCodecVersion<
+	TDecoded,
+	TContext,
+	TFormatVersion extends FormatVersion,
+	TBuildOptions extends CodecWriteOptions,
+> extends CodecVersionBase<
+		(
+			options: TBuildOptions,
+		) => IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>,
+		TFormatVersion
+	> {}
+
+/**
+ * {@link NormalizedCodecVersion} after applying the build options.
+ * @remarks
+ * Produced by {@link ClientVersionDispatchingCodecBuilder.applyOptions}.
+ */
+export interface EvaluatedCodecVersion<
+	TDecoded,
+	TContext,
+	TFormatVersion extends FormatVersion,
+> extends CodecVersionBase<
+		IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>,
+		TFormatVersion
+	> {}
+
+/**
+ * Normalize the codec to a single format.
+ * @remarks
+ * Bakes in schema validation, so output no longer exposes the schema.
+ */
+function normalizeCodecVersion<
+	TDecoded,
+	TContext,
+	TFormatVersion extends FormatVersion,
+	TBuildOptions extends CodecWriteOptions,
+>(
+	codecVersion: CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>,
+): NormalizedCodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions> {
+	const codecBuilder: (options: TBuildOptions) => CodecAndSchema<TDecoded, TContext> =
+		typeof codecVersion.codec === "function"
+			? codecVersion.codec
+			: () => codecVersion.codec as CodecAndSchema<TDecoded, TContext>;
+	const codec = (
+		options: TBuildOptions,
+	): IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext> => {
+		const built = codecBuilder(options);
+		// We currently don't expose or use binary formats, but someday we might.
+		const multiFormat = ensureBinaryEncoding<TDecoded, TContext, VersionedJson>(built);
+		return makeVersionedValidatedCodec(
+			options,
+			new Set([codecVersion.formatVersion]),
+			built.schema,
+			multiFormat.json,
+		);
+	};
+
+	return {
+		formatVersion: codecVersion.formatVersion,
+		codec,
+	};
+}
+
 /**
  * Creates a codec which dispatches to the appropriate member of a codec family based on the `minVersionForCollab` for encode and the
  * version number in data it encounters for decode.
  * @privateRemarks
  * This is a two stage builder so the first stage can encapsulate all codec specific details and the second can bring in configuration.
  */
-export class ClientVersionDispatchingCodecBuilder<TDecoded, TContext> {
-	public constructor(
+export class ClientVersionDispatchingCodecBuilder<
+	Name extends CodecName,
+	TDecoded,
+	TContext,
+	TFormatVersion extends FormatVersion,
+	TBuildOptions extends CodecWriteOptions,
+> {
+	public readonly registry: ReadonlyMap<
+		MinimumVersionForCollab,
+		NormalizedCodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>
+	>;
+
+	/**
+	 * Use {@link ClientVersionDispatchingCodecBuilder.build} to create an instance of this class.
+	 */
+	private constructor(
 		/**
-		 * The codec family to dispatch to.
+		 * See {@link CodecName}.
 		 */
-		private readonly family: ICodecFamily<TDecoded, TContext>,
+		public readonly name: Name,
 		/**
-		 * A function which maps a {@link MinimumVersionForCollab} to a version number for the codec family which is supported by that version.
-		 * This can (and typically does) pick the newest version of the codec which is known to be compatible with the client version so that
-		 * any improvements in newer versions of the codec can be used when allowed.
+		 * The registry of codecs which this builder can use to encode and decode data.
 		 */
-		private readonly versionMapping: (minVersionForCollab: MinimumVersionForCollab) => number,
-	) {}
+		inputRegistry: ConfigMapEntry<
+			CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>
+		>,
+	) {
+		type Normalized = NormalizedCodecVersion<
+			TDecoded,
+			TContext,
+			TFormatVersion,
+			TBuildOptions
+		>;
+		const normalizedRegistry = new Map<MinimumVersionForCollab, Normalized>();
+
+		for (const [minVersionForCollab, codec] of Object.entries(inputRegistry) as Iterable<
+			[
+				MinimumVersionForCollab,
+				CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>,
+			]
+		>) {
+			const normalizedCodec = normalizeCodecVersion(codec);
+			normalizedRegistry.set(minVersionForCollab, normalizedCodec);
+		}
+
+		this.registry = normalizedRegistry;
+	}
 
+	/**
+	 * Applies the provided options to the codec registry to produce a list of evaluated codecs.
+	 * @remarks
+	 * This is used by build, which is what production code should use.
+	 * This is only exposed for testing purposes.
+	 */
+	public applyOptions(
+		options: TBuildOptions,
+	): [MinimumVersionForCollab, EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>][] {
+		return Array.from(
+			this.registry,
+			([version, codec]) =>
+				[
+					version,
+					{
+						formatVersion: codec.formatVersion,
+						codec: codec.codec(options),
+					},
+				] as const,
+		);
+	}
+
+	/**
+	 * Produce a single codec which can read any supported format, and writes a version selected based on the provided options.
+	 */
 	public build(
-		options: CodecWriteOptions,
+		options: TBuildOptions,
 	): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
-		const writeVersion = this.versionMapping(options.minVersionForCollab);
-		return makeVersionDispatchingCodec(this.family, { ...options, writeVersion });
+		const applied = this.applyOptions(options);
+		const writeVersion = getWriteVersion(this.name, options, applied);
+		const fromFormatVersion = new Map<
+			FormatVersion,
+			EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>
+		>(applied.map(([_version, codec]) => [codec.formatVersion, codec]));
+		return {
+			encode: (data: TDecoded, context: TContext): JsonCompatibleReadOnly => {
+				return writeVersion.codec.encode(data, context);
+			},
+			decode: (data: JsonCompatibleReadOnly, context: TContext): TDecoded => {
+				const versioned = data as Partial<Versioned>;
+				const codec = fromFormatVersion.get(versioned.version);
+				if (codec === undefined) {
+					throw new UsageError(
+						`Unsupported version ${versioned.version} encountered while decoding ${this.name} data. Supported versions for this data are: ${versionList(applied)}.
+The client which encoded this data likely specified an "minVersionForCollab" value which corresponds to a version newer than the version of this client ("${pkgVersion}").`,
+					);
+				}
+				return codec.codec.decode(data, context);
+			},
+		};
+	}
+
+	public getCodecTree(clientVersion: MinimumVersionForCollab): CodecTree {
+		// TODO: add support for children codecs.
+		const selected = getConfigForMinVersionForCollabIterable(clientVersion, this.registry);
+		return {
+			name: this.name,
+			version: selected.formatVersion,
+		};
 	}
+
+	/**
+	 * Builds a ClientVersionDispatchingCodecBuilder from the provided registry.
+	 * @remarks
+	 * This static method infers the types of the builder from the provided registry,
+	 * making it easier to create builders without needing to explicitly specify all type parameters.
+	 * This gets better type inference than the constructor.
+	 */
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+	public static build<
+		Name extends CodecName,
+		Entry extends CodecVersion<unknown, unknown, FormatVersion, never>,
+	>(name: Name, inputRegistry: ConfigMapEntry<Entry>) {
+		type TDecoded2 = Entry extends CodecVersion<infer D, unknown, FormatVersion, never>
+			? D
+			: never;
+		type TContext2 = Entry extends CodecVersion<unknown, infer C, FormatVersion, never>
+			? C
+			: never;
+		type TFormatVersion2 = Entry extends CodecVersion<unknown, unknown, infer F, never>
+			? F
+			: never;
+		type TBuildOptions2 = Entry extends CodecVersion<unknown, unknown, FormatVersion, infer B>
+			? B
+			: never;
+		const builder = new ClientVersionDispatchingCodecBuilder(
+			name,
+			inputRegistry as ConfigMapEntry<unknown> as ConfigMapEntry<
+				CodecVersion<
+					TDecoded2,
+					// If it does not matter what context is provided, undefined is fine, so allow it to be omitted.
+					TContext2 extends unknown ? void : TContext2,
+					TFormatVersion2,
+					TBuildOptions2
+				>
+			>,
+		);
+		return builder;
+	}
+}
+
+/**
+ * Selects which format should be used when writing data.
+ * @remarks
+ * This either uses the override specified in the options, or selects the newest format compatible with the provided minVersionForCollab.
+ */
+function getWriteVersion<T extends CodecVersionBase>(
+	name: CodecName,
+	options: CodecWriteOptions,
+	versions: readonly [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][],
+): T {
+	if (options.writeVersionOverrides?.has(name) === true) {
+		const selectedFormatVersion = options.writeVersionOverrides.get(name);
+		const selected = versions.find(
+			([_v, codec]) => codec.formatVersion === selectedFormatVersion,
+		);
+		if (selected === undefined) {
+			throw new UsageError(
+				`Codec "${name}" does not support requested format version ${selectedFormatVersion}. Supported versions are: ${versionList(versions)}.`,
+			);
+		} else if (options.allowPossiblyIncompatibleWriteVersionOverrides !== true) {
+			const selectedMinVersionForCollab = selected[0];
+			// Currently all versions must specify a minVersionForCollab, so undefined is not expected here.
+			// TODO: It should be possible to have a version which would never be automatically selected for write (and thus does not have or need a minVersionForCollab), but can be selected via override.
+			// Use-cases for this include experimental versions not yet stable, and discontinued or intermediate versions which are mainly being kept for read compatibility but still support writing (perhaps for round-trip testing).
+			// For now, this check should never pass, and there is no way to create such a version yet.
+			if (selectedMinVersionForCollab === undefined) {
+				throw new UsageError(
+					`Codec "${name}" does not support requested format version ${selectedFormatVersion} because it does not specify a minVersionForCollab. Use "allowPossiblyIncompatibleWriteVersionOverrides" to suppress this error if appropriate.`,
+				);
+			} else if (gt(selectedMinVersionForCollab, options.minVersionForCollab)) {
+				throw new UsageError(
+					`Codec "${name}" does not support requested format version ${selectedFormatVersion} because it is only compatible back to client version ${selectedMinVersionForCollab} and the requested oldest compatible client was ${options.minVersionForCollab}. Use "allowPossiblyIncompatibleWriteVersionOverrides" to suppress this error if appropriate.`,
+				);
+			}
+		}
+
+		return selected[1];
+	}
+	const result: T = getConfigForMinVersionForCollabIterable(
+		options.minVersionForCollab,
+		versions,
+	);
+	return result;
+}
+
+/**
+ * Formats a list of versions for use in UsageErrors.
+ */
+function versionList(
+	versions: readonly [
+		MinimumMinorSemanticVersion | MinimumVersionForCollab,
+		CodecVersionBase,
+	][],
+): string {
+	return `${Array.from(versions, ([_v, codec]) => codec.formatVersion).join(", ")}`;
 }

package/src/codec/versioned/index.ts

@@ -5,8 +5,10 @@
 
 export { Versioned } from "./format.js";
 export {
-	makeVersionedCodec,
 	makeVersionedValidatedCodec,
 	makeVersionDispatchingCodec,
 	makeDiscontinuedCodecVersion,
+	ClientVersionDispatchingCodecBuilder,
+	type CodecVersion,
+	type CodecAndSchema,
 } from "./codec.js";