@fluidframework/tree 2.74.0 → 2.81.0-374083

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";

package/src/core/change-family/changeFamily.ts

@@ -14,12 +14,17 @@ export interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {
 	buildEditor(
 		mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<TChange>) => void,
+		options?: EditorOptions,
 	): TEditor;
 
 	readonly rebaser: ChangeRebaser<TChange>;
 	readonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;
 }
 
+export interface EditorOptions {
+	readonly canMakeDetachedRootEdits: boolean; // default is false,
+}
+
 export interface ChangeEncodingContext {
 	readonly originatorId: SessionId;
 	readonly revision: RevisionTag | undefined;

package/src/core/change-family/index.ts

@@ -8,5 +8,6 @@ export type {
 	ChangeFamilyEditor,
 	ChangeEncodingContext,
 	ChangeFamilyCodec,
+	EditorOptions,
 } from "./changeFamily.js";
 export { EditBuilder } from "./editBuilder.js";

package/src/core/index.ts

@@ -74,7 +74,7 @@ export {
 	type AnchorNode,
 	anchorSlot,
 	type UpPathDefault,
-	isDetachedUpPath,
+	isDetachedUpPathRoot,
 	inCursorField,
 	inCursorNode,
 	type AnchorEvents,
@@ -87,6 +87,7 @@ export {
 	type DetachedFieldIndexCheckpoint,
 	type ForestRootId,
 	getDetachedFieldContainingPath,
+	getDetachedFieldContainingFieldPath,
 	aboveRootPlaceholder,
 	type DeltaRoot,
 	type DeltaMark,
@@ -105,7 +106,7 @@ export {
 	tryGetChunk,
 	type ChunkedCursor,
 	DetachedFieldIndexFormatVersion,
-	getCodecTreeForDetachedFieldIndexFormat,
+	detachedFieldIndexCodecBuilder,
 } from "./tree/index.js";
 
 export {
@@ -162,6 +163,7 @@ export {
 	type ChangeEncodingContext,
 	type ChangeFamilyEditor,
 	EditBuilder,
+	type EditorOptions,
 } from "./change-family/index.js";
 
 export {
@@ -175,6 +177,8 @@ export {
 	type GraphCommit,
 	CommitKind,
 	type CommitMetadata,
+	type LocalChangeMetadata,
+	type RemoteChangeMetadata,
 	type ChangeMetadata,
 	type RevisionTag,
 	RevisionTagSchema,
@@ -204,15 +208,16 @@ export {
 	offsetChangeAtomId,
 	StableIdSchema,
 	subtractChangeAtomIds,
-	replaceAtomRevisions,
 	replaceChange,
 	type RebaseStats,
 	type RebaseStatsWithDuration,
 	isAncestor,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
+	newChangeAtomIdTransform,
 	compareRevisions,
 	diffHistories,
+	type RevisionReplacer,
 } from "./rebase/index.js";
 
 export {

package/src/core/rebase/changeRebaser.ts

@@ -5,7 +5,7 @@
 
 import type { Invariant } from "../../util/index.js";
 
-import type { RevisionTag } from "./types.js";
+import type { ChangeAtomId, RevisionTag } from "./types.js";
 
 /**
  * Rebasing logic for a particular kind of change.
@@ -89,11 +89,45 @@ export interface ChangeRebaser<TChangeset> {
 		revisionMetadata: RevisionMetadataSource,
 	): TChangeset;
 
-	changeRevision(
-		change: TChangeset,
-		newRevision: RevisionTag | undefined,
-		rollBackOf?: RevisionTag,
-	): TChangeset;
+	/**
+	 * Retrieves the set of revisions associated with the given change.
+	 */
+	getRevisions(change: TChangeset): Set<RevisionTag | undefined>;
+
+	/**
+	 * Produces a changeset that is equivalent to the given `change`, but with all references to its own revisions replaced according to the given `replacer`.
+	 * @param change - The change to update. Not modified.
+	 * @param replacer - The replacer to use.
+	 * @returns A changeset equivalent to `change`, but with all references to its own revision replaced according to `replacer`.
+	 */
+	changeRevision(change: TChangeset, replacer: RevisionReplacer): TChangeset;
+}
+
+/**
+ * A type that can update references to a set of obsolete revisions across multiple changesets.
+ */
+export interface RevisionReplacer {
+	/**
+	 * The revision to use in place of the obsolete revisions.
+	 */
+	readonly updatedRevision: RevisionTag;
+
+	/**
+	 * Predicate to determine if a revision needs replacing.
+	 * @param revision - The revision that may need replacing.
+	 * @returns true iff the given `revision` needs replacing.
+	 */
+	isObsolete(revision: RevisionTag | undefined): boolean;
+
+	/**
+	 * Returns the updated ID for the given ID.
+	 * @param id - The ID to update.
+	 * @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;
 }
 
 export interface TaggedChange<TChangeset, TTag = RevisionTag | undefined> {
@@ -126,7 +160,12 @@ export function mapTaggedChange<TIn, TOut>(
 export type RevisionIndexer = (tag: RevisionTag) => number | undefined;
 
 export interface RevisionMetadataSource {
-	readonly getIndex: RevisionIndexer;
+	/**
+	 * @returns a positive number if tag2 is a later revision than tag1 or a negative number if tag2 is an earlier revision.
+	 * Returns zero is the order cannot be determined, which happens if both revisions are older
+	 * than the set of revisions handled by this metadata source.
+	 */
+	readonly compareRevisions: (tag1: RevisionTag, tag2: RevisionTag) => number;
 	readonly tryGetInfo: (tag: RevisionTag | undefined) => RevisionInfo | undefined;
 	readonly hasRollback: (tag: RevisionTag) => boolean;
 }

package/src/core/rebase/index.ts

@@ -12,6 +12,8 @@ export {
 	type GraphCommit,
 	CommitKind,
 	type CommitMetadata,
+	type LocalChangeMetadata,
+	type RemoteChangeMetadata,
 	type ChangeMetadata,
 	type RevisionTag,
 	RevisionTagSchema,
@@ -27,9 +29,9 @@ export {
 	offsetChangeAtomId,
 	StableIdSchema,
 	subtractChangeAtomIds,
-	replaceAtomRevisions,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
+	newChangeAtomIdTransform,
 	compareRevisions,
 } from "./types.js";
 export { RevisionTagCodec } from "./revisionTagCodec.js";
@@ -44,6 +46,7 @@ export {
 	type TaggedChange,
 	type RevisionMetadataSource,
 	type RevisionInfo,
+	type RevisionReplacer,
 } from "./changeRebaser.js";
 export {
 	findAncestor,