@fluidframework/tree 2.81.1 → 2.83.0

package/src/codec/versioned/codec.ts

@@ -3,11 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, debugAssert } from "@fluidframework/core-utils/internal";
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 import {
 	getConfigForMinVersionForCollabIterable,
-	type ConfigMapEntry,
+	lowestMinVersionForCollab,
 	type MinimumMinorSemanticVersion,
 	type SemanticVersion,
 } from "@fluidframework/runtime-utils/internal";
@@ -27,9 +27,7 @@ import {
 	withSchemaValidation,
 	type FormatVersion,
 	type CodecWriteOptions,
-	type IMultiFormatCodec,
 	type CodecName,
-	ensureBinaryEncoding,
 	type CodecTree,
 } from "../codec.js";
 
@@ -151,7 +149,7 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
 	family: ICodecFamily<TDecoded, TContext>,
 	options: ICodecOptions & { writeVersion: FormatVersion },
 ): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
-	const writeCodec = family.resolve(options.writeVersion).json;
+	const writeCodec = family.resolve(options.writeVersion);
 	const supportedVersions = new Set(family.getSupportedFormats());
 	return makeVersionedCodec(supportedVersions, options, {
 		encode(data, context): Versioned {
@@ -159,7 +157,7 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
 		},
 		decode(data: Versioned, context) {
 			const codec = family.resolve(data.version);
-			return codec.json.decode(data, context);
+			return codec.decode(data, context);
 		},
 	});
 }
@@ -170,10 +168,9 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
  * 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>
-);
+export type CodecAndSchema<TDecoded, TContext = void> = {
+	readonly schema: TSchema;
+} & IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>;
 
 /**
  * A codec alongside its format version and schema.
@@ -182,6 +179,14 @@ export interface CodecVersionBase<
 	T = unknown,
 	TFormatVersion extends FormatVersion = FormatVersion,
 > {
+	/**
+	 * When `undefined` the codec will never be selected as a write version except via override.
+	 * @remarks
+	 * This format will be used for decode if data in it needs to be decoded, regardless of `minVersionForCollab`.
+	 * `undefined` should be used for unstable codec versions (with string FormatVersions),
+	 * as well as previously stabilized formats that are discontinued (meaning we always prefer to use some other format for encoding).
+	 */
+	readonly minVersionForCollab: MinimumVersionForCollab | undefined;
 	readonly formatVersion: TFormatVersion;
 	readonly codec: T;
 }
@@ -228,11 +233,8 @@ export interface NormalizedCodecVersion<
  * @remarks
  * Produced by {@link ClientVersionDispatchingCodecBuilder.applyOptions}.
  */
-export interface EvaluatedCodecVersion<
-	TDecoded,
-	TContext,
-	TFormatVersion extends FormatVersion,
-> extends CodecVersionBase<
+interface EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion extends FormatVersion>
+	extends CodecVersionBase<
 		IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>,
 		TFormatVersion
 	> {}
@@ -258,17 +260,16 @@ function normalizeCodecVersion<
 		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,
+			built,
 		);
 	};
 
 	return {
+		minVersionForCollab: codecVersion.minVersionForCollab,
 		formatVersion: codecVersion.formatVersion,
 		codec,
 	};
@@ -287,13 +288,20 @@ export class ClientVersionDispatchingCodecBuilder<
 	TFormatVersion extends FormatVersion,
 	TBuildOptions extends CodecWriteOptions,
 > {
-	public readonly registry: ReadonlyMap<
-		MinimumVersionForCollab,
-		NormalizedCodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>
-	>;
+	public readonly registry: readonly NormalizedCodecVersion<
+		TDecoded,
+		TContext,
+		TFormatVersion,
+		TBuildOptions
+	>[];
 
 	/**
 	 * Use {@link ClientVersionDispatchingCodecBuilder.build} to create an instance of this class.
+	 * @remarks
+	 * Inputs to this are assumed to be constants in the code controlled by the developers of this package,
+	 * and constructed at least once during tests.
+	 * Because of this, the validation of these inputs done with debugAssert should be sufficient,
+	 * and using debugAssert avoids bloating the bundle size for production users.
 	 */
 	private constructor(
 		/**
@@ -303,9 +311,7 @@ export class ClientVersionDispatchingCodecBuilder<
 		/**
 		 * The registry of codecs which this builder can use to encode and decode data.
 		 */
-		inputRegistry: ConfigMapEntry<
-			CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>
-		>,
+		inputRegistry: readonly CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>[],
 	) {
 		type Normalized = NormalizedCodecVersion<
 			TDecoded,
@@ -313,18 +319,41 @@ export class ClientVersionDispatchingCodecBuilder<
 			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 normalizedRegistry: Normalized[] = [];
+		const formats: Set<FormatVersion> = new Set();
+		const versions: Set<string | undefined> = new Set();
+
+		for (const codec of inputRegistry) {
+			debugAssert(
+				() =>
+					!formats.has(codec.formatVersion) ||
+					`duplicate codec format ${name} ${codec.formatVersion}`,
+			);
+			debugAssert(
+				() =>
+					codec.minVersionForCollab === undefined ||
+					typeof codec.formatVersion !== "string" ||
+					`unstable format ${JSON.stringify(codec.formatVersion)} (string formats) must not have a minVersionForCollab in ${name}`,
+			);
+			formats.add(codec.formatVersion);
 			const normalizedCodec = normalizeCodecVersion(codec);
-			normalizedRegistry.set(minVersionForCollab, normalizedCodec);
+			normalizedRegistry.push(normalizedCodec);
+			if (codec.minVersionForCollab !== undefined) {
+				debugAssert(
+					() =>
+						!versions.has(codec.minVersionForCollab) ||
+						`Codec ${name} has multiple entries for version ${JSON.stringify(codec.minVersionForCollab)}`,
+				);
+				versions.add(codec.minVersionForCollab);
+			}
 		}
 
+		debugAssert(
+			() =>
+				versions.has(lowestMinVersionForCollab) ||
+				`Codec ${name} is missing entry for lowestMinVersionForCollab`,
+		);
+
 		this.registry = normalizedRegistry;
 	}
 
@@ -336,18 +365,12 @@ export class ClientVersionDispatchingCodecBuilder<
 	 */
 	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,
-		);
+	): EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>[] {
+		return this.registry.map((codec) => ({
+			minVersionForCollab: codec.minVersionForCollab,
+			formatVersion: codec.formatVersion,
+			codec: codec.codec(options),
+		}));
 	}
 
 	/**
@@ -361,7 +384,7 @@ export class ClientVersionDispatchingCodecBuilder<
 		const fromFormatVersion = new Map<
 			FormatVersion,
 			EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>
-		>(applied.map(([_version, codec]) => [codec.formatVersion, codec]));
+		>(applied.map((codec) => [codec.formatVersion, codec]));
 		return {
 			encode: (data: TDecoded, context: TContext): JsonCompatibleReadOnly => {
 				return writeVersion.codec.encode(data, context);
@@ -382,7 +405,7 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 
 	public getCodecTree(clientVersion: MinimumVersionForCollab): CodecTree {
 		// TODO: add support for children codecs.
-		const selected = getConfigForMinVersionForCollabIterable(clientVersion, this.registry);
+		const selected = getWriteVersionNoOverrides(this.registry, clientVersion);
 		return {
 			name: this.name,
 			version: selected.formatVersion,
@@ -400,31 +423,33 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 	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
-				>
-			>,
-		);
+	>(name: Name, inputRegistry: readonly 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;
+
+		type CodecFinal = CodecVersion<
+			TDecoded2,
+			// If it does not matter what context is provided, undefined is fine, so allow it to be omitted.
+			unknown extends TContext2 ? void : TContext2,
+			TFormatVersion2,
+			TBuildOptions2
+		>;
+
+		const input = inputRegistry as readonly unknown[] as readonly CodecFinal[];
+
+		const builder = new ClientVersionDispatchingCodecBuilder<
+			Name,
+			TDecoded2,
+			unknown extends TContext2 ? void : TContext2,
+			TFormatVersion2,
+			TBuildOptions2
+		>(name, input);
 		return builder;
 	}
 }
@@ -437,39 +462,51 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 function getWriteVersion<T extends CodecVersionBase>(
 	name: CodecName,
 	options: CodecWriteOptions,
-	versions: readonly [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][],
+	versions: readonly T[],
 ): T {
 	if (options.writeVersionOverrides?.has(name) === true) {
 		const selectedFormatVersion = options.writeVersionOverrides.get(name);
-		const selected = versions.find(
-			([_v, codec]) => codec.formatVersion === selectedFormatVersion,
-		);
+		const selected = versions.find((codec) => codec.formatVersion === selectedFormatVersion);
 		if (selected === undefined) {
 			throw new UsageError(
-				`Codec "${name}" does not support requested format version ${selectedFormatVersion}. Supported versions are: ${versionList(versions)}.`,
+				`Codec "${name}" does not support requested format version ${JSON.stringify(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.
+			const selectedMinVersionForCollab = selected.minVersionForCollab;
 			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.`,
+					`Codec "${name}" does not support requested format version ${JSON.stringify(selectedFormatVersion)} because it has minVersionForCollab undefined. 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.`,
+					`Codec "${name}" does not support requested format version ${JSON.stringify(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];
+		return selected;
 	}
+
+	return getWriteVersionNoOverrides(versions, options.minVersionForCollab);
+}
+
+/**
+ * Selects which format should be used when writing data, without consider overrides.
+ */
+function getWriteVersionNoOverrides<T extends CodecVersionBase>(
+	versions: readonly T[],
+	minVersionForCollab: MinimumVersionForCollab,
+): T {
+	const stableVersions: [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][] = [];
+	for (const version of versions) {
+		if (version.minVersionForCollab !== undefined) {
+			stableVersions.push([version.minVersionForCollab, version]);
+		}
+	}
+
 	const result: T = getConfigForMinVersionForCollabIterable(
-		options.minVersionForCollab,
-		versions,
+		minVersionForCollab,
+		stableVersions,
 	);
 	return result;
 }
@@ -477,11 +514,6 @@ function getWriteVersion<T extends CodecVersionBase>(
 /**
  * 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(", ")}`;
+function versionList(versions: readonly CodecVersionBase[]): string {
+	return JSON.stringify(Array.from(versions, (codec) => codec.formatVersion));
 }

package/src/core/index.ts

@@ -212,7 +212,9 @@ export {
 	isAncestor,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
-	compareRevisions,
+	comparePartialRevisions,
+	compareChangesetLocalIds,
+	comparePartialChangesetLocalIds,
 	diffHistories,
 	type RevisionReplacer,
 } from "./rebase/index.js";

package/src/core/rebase/changeRebaser.ts

@@ -121,13 +121,14 @@ export interface RevisionReplacer {
 
 	/**
 	 * Returns the updated ID for the given ID.
-	 * @param id - The ID to update.
+	 * @param id - The ID of the first change atom to update.
+	 * @param count - The number of contiguous change atoms to update. Defaults to 1.
 	 * @returns an updated ID iff the given `id` needs updating, otherwise returns the given `id`.
 	 * @remarks
 	 * This function always maps the same input {@link ChangeAtomId.revision | revision} and {@link ChangeAtomId.localId | local ID} to the same output revision local ID.
 	 * This means multiple references to the same atom of change will remain consistent after revision replacement.
 	 */
-	getUpdatedAtomId<T extends ChangeAtomId>(id: T): T;
+	getUpdatedAtomId<T extends ChangeAtomId>(id: T, count?: number): T;
 }
 
 export interface TaggedChange<TChangeset, TTag = RevisionTag | undefined> {

package/src/core/rebase/index.ts

@@ -31,7 +31,9 @@ export {
 	subtractChangeAtomIds,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
-	compareRevisions,
+	comparePartialRevisions,
+	compareChangesetLocalIds,
+	comparePartialChangesetLocalIds,
 } from "./types.js";
 export { RevisionTagCodec } from "./revisionTagCodec.js";
 export {

package/src/core/rebase/types.ts

@@ -19,6 +19,7 @@ import {
 	brand,
 	brandedNumberType,
 	brandedStringType,
+	comparePartialStrings,
 } from "../../util/index.js";
 import type { RevertibleAlpha } from "../revertible.js";
 
@@ -46,6 +47,9 @@ export const StableIdSchema = Type.String();
 
 /**
  * An ID which is unique within a revision of a `ModularChangeset`.
+ * @remarks
+ * Always a real number (never `NaN` or +/- `Infinity`).
+ *
  * A `ModularChangeset` which is a composition of multiple revisions may contain duplicate `ChangesetLocalId`s,
  * but they are unique when qualified by the revision of the change they are used in.
  */
@@ -122,10 +126,30 @@ export function taggedOptAtomId(
 	return taggedAtomId(id, revision);
 }
 
-export function offsetChangeAtomId(id: ChangeAtomId, offset: number): ChangeAtomId {
+export function offsetChangeAtomId<T extends ChangeAtomId>(id: T, offset: number): T {
 	return { ...id, localId: brand(id.localId + offset) };
 }
 
+// #region These comparison functions are used instead of e.g. `compareNumbers` as a performance optimization
+
+export function compareChangesetLocalIds(a: ChangesetLocalId, b: ChangesetLocalId): number {
+	return a - b; // No need to consider `NaN` or `Infinity` since ChangesetLocalId is always a real number
+}
+
+export function comparePartialChangesetLocalIds(
+	a: ChangesetLocalId | undefined,
+	b: ChangesetLocalId | undefined,
+): number {
+	if (a === undefined) {
+		return b === undefined ? 0 : -1;
+	} else if (b === undefined) {
+		return 1;
+	}
+	return compareChangesetLocalIds(a, b);
+}
+
+// #endregion
+
 /**
  * A node in a graph of commits. A commit's parent is the commit on which it was based.
  */
@@ -204,6 +228,12 @@ export interface LocalChangeMetadata extends CommitMetadata {
 	getRevertible(
 		onDisposed?: (revertible: RevertibleAlpha) => void,
 	): RevertibleAlpha | undefined;
+
+	/**
+	 * Optional label provided by the user when commit was created.
+	 * This can be used by undo/redo to group or classify edits.
+	 */
+	readonly label?: unknown;
 }
 
 /**
@@ -225,6 +255,11 @@ export interface RemoteChangeMetadata extends CommitMetadata {
 	 * @remarks This is only available for {@link LocalChangeMetadata | local changes}.
 	 */
 	readonly getRevertible?: undefined;
+	/**
+	 * Label provided by the user when commit was created.
+	 * @remarks This is only available for {@link LocalChangeMetadata | local changes}.
+	 */
+	readonly label?: undefined;
 }
 
 /**
@@ -255,12 +290,14 @@ export function mintCommit<TChange>(
 
 export type ChangeAtomIdRangeMap<V> = RangeMap<ChangeAtomId, V>;
 
-export function newChangeAtomIdRangeMap<V>(): ChangeAtomIdRangeMap<V> {
-	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds);
+export function newChangeAtomIdRangeMap<V>(
+	offsetValue?: (value: V, offset: number) => V,
+): ChangeAtomIdRangeMap<V> {
+	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetValue);
 }
 
 export function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number {
-	const cmp = compareRevisions(a.revision, b.revision);
+	const cmp = comparePartialRevisions(a.revision, b.revision);
 	if (cmp !== 0) {
 		return cmp * Number.POSITIVE_INFINITY;
 	}
@@ -268,19 +305,20 @@ export function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number
 	return a.localId - b.localId;
 }
 
-export function compareRevisions(
+/**
+ * Compares two {@link RevisionTag}s to form a strict total ordering.
+ * @remarks This function tolerates arbitrary strings, not just the string "root".
+ * It sorts as follows: `undefined` \< `string` \< `number`
+ */
+export function comparePartialRevisions(
 	a: RevisionTag | undefined,
 	b: RevisionTag | undefined,
 ): number {
-	if (a === undefined) {
-		return b === undefined ? 0 : -1;
-	} else if (b === undefined) {
-		return 1;
-	} else if (a < b) {
+	if (typeof a === "number") {
+		return typeof b === "number" ? a - b : 1;
+	} else if (typeof b === "number") {
 		return -1;
-	} else if (a > b) {
-		return 1;
 	}
 
-	return 0;
+	return comparePartialStrings(a, b);
 }

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

@@ -52,6 +52,7 @@ const FieldSchemaFormatBase = Type.Object({
 
 const noAdditionalProps: ObjectOptions = { additionalProperties: false };
 
+export type FieldSchemaFormat = Static<typeof FieldSchemaFormat>;
 export const FieldSchemaFormat = Type.Composite([FieldSchemaFormatBase], noAdditionalProps);
 
 /**
@@ -70,6 +71,7 @@ export enum PersistedValueSchema {
  *
  * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
  */
+export type TreeNodeSchemaDataFormat = Static<typeof TreeNodeSchemaDataFormat>;
 export const TreeNodeSchemaDataFormat = Type.Object(
 	{
 		/**
@@ -87,7 +89,3 @@ export const TreeNodeSchemaDataFormat = Type.Object(
 	},
 	unionOptions,
 );
-
-export type TreeNodeSchemaDataFormat = Static<typeof TreeNodeSchemaDataFormat>;
-
-export type FieldSchemaFormat = Static<typeof FieldSchemaFormat>;

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

@@ -6,6 +6,7 @@
 import { type ObjectOptions, type Static, Type } from "@sinclair/typebox";
 
 import { unionOptions } from "../../codec/index.js";
+import type { JsonCompatibleReadOnlyObject } from "../../util/index.js";
 import { JsonCompatibleReadOnlySchema } from "../../util/index.js";
 
 import {
@@ -14,7 +15,12 @@ import {
 	TreeNodeSchemaIdentifierSchema,
 } from "./formatV1.js";
 
-export const PersistedMetadataFormat = Type.Optional(JsonCompatibleReadOnlySchema);
+export type PersistedMetadataFormat = Static<typeof PersistedMetadataFormat>;
+export const PersistedMetadataFormat = Type.Optional(
+	Type.Unsafe<JsonCompatibleReadOnlyObject>(
+		Type.Record(Type.String(), JsonCompatibleReadOnlySchema),
+	),
+);
 
 const FieldSchemaFormatBase = Type.Object({
 	kind: FieldKindIdentifierSchema,
@@ -24,6 +30,7 @@ const FieldSchemaFormatBase = Type.Object({
 
 const noAdditionalProps: ObjectOptions = { additionalProperties: false };
 
+export type FieldSchemaFormat = Static<typeof FieldSchemaFormat>;
 export const FieldSchemaFormat = Type.Composite([FieldSchemaFormatBase], noAdditionalProps);
 
 /**
@@ -56,6 +63,7 @@ export type TreeNodeSchemaUnionFormat = Static<typeof TreeNodeSchemaUnionFormat>
  *
  * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
  */
+export type TreeNodeSchemaDataFormat = Static<typeof TreeNodeSchemaDataFormat>;
 export const TreeNodeSchemaDataFormat = Type.Object(
 	{
 		/**
@@ -71,9 +79,3 @@ export const TreeNodeSchemaDataFormat = Type.Object(
 	},
 	noAdditionalProps,
 );
-
-export type TreeNodeSchemaDataFormat = Static<typeof TreeNodeSchemaDataFormat>;
-
-export type FieldSchemaFormat = Static<typeof FieldSchemaFormat>;
-
-export type PersistedMetadataFormat = Static<typeof PersistedMetadataFormat>;

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

@@ -37,6 +37,8 @@ export { Multiplicity } from "./multiplicity.js";
 export type { TreeNodeSchemaIdentifier, FieldKey, FieldKindIdentifier } from "./formatV1.js";
 
 import * as schemaFormatV1 from "./formatV1.js";
+// eslint-disable-next-line unicorn/prefer-export-from -- fixing requires `export * as` (breaks API-Extractor) or named exports (changes public API)
 export { schemaFormatV1 };
 import * as schemaFormatV2 from "./formatV2.js";
+// eslint-disable-next-line unicorn/prefer-export-from -- fixing requires `export * as` (breaks API-Extractor) or named exports (changes public API)
 export { schemaFormatV2 };

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

@@ -253,7 +253,10 @@ export class ObjectNodeStoredSchema extends TreeNodeStoredSchema {
 	private encodeFieldsObject(
 		encodeFieldSchema: (storedFieldSchema: TreeFieldStoredSchema) => FieldSchemaFormat,
 	): Record<string, FieldSchemaFormat> {
-		const fieldsObject: Record<string, FieldSchemaFormat> = Object.create(null);
+		const fieldsObject: Record<string, FieldSchemaFormat> = Object.create(null) as Record<
+			string,
+			FieldSchemaFormat
+		>;
 		// Sort fields to ensure output is identical for for equivalent schema (since field order is not considered significant).
 		// This makes comparing schema easier, and ensures chunk reuse for schema summaries isn't needlessly broken.
 		for (const key of [...this.objectNodeFields.keys()].sort()) {

package/src/core/tree/anchorSet.ts

@@ -128,9 +128,7 @@ export interface AnchorEvents {
 	 *
 	 * Compare to {@link AnchorEvents.childrenChanged} which is emitted in the middle of the batch/delta-visit.
 	 */
-	childrenChangedAfterBatch(arg: {
-		changedFields: ReadonlySet<FieldKey>;
-	}): void;
+	childrenChangedAfterBatch(arg: { changedFields: ReadonlySet<FieldKey> }): void;
 
 	/**
 	 * Emitted in the middle of applying a batch of changes (i.e. during a delta a visit), if something in the subtree

package/src/core/tree/delta.ts

@@ -196,10 +196,12 @@ export interface DetachedNodeRename {
 	readonly newId: DetachedNodeId;
 }
 
-/**
- * Represents a list of changes to the nodes in the field.
- * The index of each mark within the range of nodes, before
- * applying any of the changes, is not represented explicitly.
- * It corresponds to the sum of `mark.count` values for all previous marks for which `isAttachMark(mark)` is false.
- */
-export type FieldChanges = readonly Mark[];
+export interface FieldChanges {
+	/**
+	 * Represents a list of changes to the nodes in the field.
+	 * The index of each mark within the range of nodes, before
+	 * applying any of the changes, is not represented explicitly.
+	 * It corresponds to the sum of `mark.count` values for all previous marks for which `isAttachMark(mark)` is false.
+	 */
+	readonly marks: readonly Mark[];
+}

package/src/core/tree/deltaUtil.ts

@@ -20,7 +20,7 @@ export function deltaForRootInitialization(content: TreeChunk): Root {
 	const delta: Root = {
 		build: [{ id: buildId, trees: content }],
 		fields: new Map<FieldKey, FieldChanges>([
-			[rootFieldKey, [{ count: content.topLevelLength, attach: buildId }]],
+			[rootFieldKey, { marks: [{ count: content.topLevelLength, attach: buildId }] }],
 		]),
 	};
 	return delta;