@fluidframework/tree 2.111.0 → 2.113.0-411909

package/src/feature-libraries/sequence-field/filterEdits.ts

@@ -0,0 +1,143 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ChangeAtomId } from "../../core/index.js";
+import type { RangeQueryResult } from "../../util/index.js";
+import { EditFilterStatus, type EditFilterFunc } from "../modular-schema/index.js";
+import { MarkListFactory } from "./markListFactory.js";
+import { NoopMarkType, type Changeset, type Mark } from "./types.js";
+import { getDetachedNodeId, getDetachOutputCellId, omitMarkEffect } from "./utils.js";
+import { MarkQueueBase } from "./markQueue.js";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
+
+export function filterEdits(
+	change: Changeset,
+	options: {
+		filterDetach: EditFilterFunc;
+		filterAttach: EditFilterFunc;
+		preserveOtherEdits: boolean;
+	},
+): Changeset {
+	const factory = new MarkListFactory();
+	const queue = new MarkQueueBase(change);
+	for (let mark = queue.peek(); mark !== undefined; mark = queue.peek()) {
+		const filtered = filterMark(
+			mark,
+			options.filterDetach,
+			options.filterAttach,
+			options.preserveOtherEdits,
+		);
+		factory.push(filtered);
+		queue.dequeueUpTo(filtered.count);
+	}
+
+	return factory.list;
+}
+
+function filterMark(
+	mark: Mark,
+	filterDetach: (
+		id: ChangeAtomId,
+		count: number,
+		endpoint?: ChangeAtomId,
+	) => RangeQueryResult<EditFilterStatus>,
+	filterAttach: (
+		id: ChangeAtomId,
+		count: number,
+		endpoint?: ChangeAtomId,
+	) => RangeQueryResult<EditFilterStatus>,
+	preserveOtherEdits: boolean,
+): Mark {
+	const type = mark.type;
+	switch (type) {
+		case "Insert":
+		case "MoveIn": {
+			if (mark.cellId === undefined) {
+				return preserveOtherEdits ? mark : omitMarkEffect(mark);
+			}
+
+			const endpoint = mark.type === "MoveIn" ? mark.finalEndpoint : undefined;
+			const result = filterAttach(mark.cellId, mark.count, endpoint);
+
+			let filtered: Mark;
+			switch (result.value) {
+				case EditFilterStatus.Preserve: {
+					filtered = mark;
+					break;
+				}
+				case EditFilterStatus.PreserveWithoutMove: {
+					// KLUDGE: PreserveWithoutMove requires us to return a mark which attaches the node
+					// using the detach ID of the move (the endpoint ID).
+					// Insert marks use the cell ID as the attach ID, so we must change the cell ID here.
+					// This could be a problem if there were references to the old cell ID outside this changeset,
+					// but PreserveWithoutMove is only used for transaction minimization, where that is not a problem.
+					const newCellId = endpoint ?? { revision: mark.revision, localId: mark.id };
+					filtered = {
+						type: "Insert",
+						count: result.length,
+						cellId: newCellId,
+						revision: mark.revision,
+						id: mark.id,
+					};
+					break;
+				}
+				case EditFilterStatus.Remove: {
+					filtered = omitMarkEffect(mark);
+					break;
+				}
+				default: {
+					unreachableCase(result.value);
+				}
+			}
+
+			return { ...filtered, count: result.length };
+		}
+		case "Remove":
+		case "MoveOut": {
+			const detachId = getDetachedNodeId(mark);
+			const endpoint = mark.type === "MoveOut" ? mark.finalEndpoint : undefined;
+			const result = filterDetach(detachId, mark.count, endpoint);
+
+			let filtered: Mark;
+			switch (result.value) {
+				case EditFilterStatus.Preserve: {
+					filtered = mark;
+					break;
+				}
+				case EditFilterStatus.PreserveWithoutMove: {
+					const outputCellId = getDetachOutputCellId(mark);
+					filtered = {
+						type: "Remove",
+						count: mark.count,
+						revision: outputCellId.revision,
+						id: outputCellId.localId,
+					};
+
+					if (mark.changes !== undefined) {
+						filtered.changes = mark.changes;
+					}
+
+					break;
+				}
+				case EditFilterStatus.Remove: {
+					filtered = omitMarkEffect(mark);
+					break;
+				}
+				default: {
+					unreachableCase(result.value);
+				}
+			}
+			return { ...filtered, count: result.length };
+		}
+		case NoopMarkType:
+		case "Rename":
+		case "AttachAndDetach": {
+			return preserveOtherEdits ? mark : omitMarkEffect(mark);
+		}
+		default: {
+			unreachableCase(type);
+		}
+	}
+}

package/src/feature-libraries/sequence-field/markQueue.ts

@@ -3,20 +3,17 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 
-import { type MoveEffectTable, splitMarkForMoveEffects } from "./moveEffectTable.js";
+import { getFirstMoveEffectLength, type MoveEffectTable } from "./moveEffectTable.js";
 import type { Mark } from "./types.js";
 import { splitMark } from "./utils.js";
 
-export class MarkQueue {
+export class MarkQueueBase {
 	private readonly stack: Mark[] = [];
 	private index = 0;
 
-	public constructor(
-		private readonly list: readonly Mark[],
-		private readonly moveEffects: MoveEffectTable,
-	) {
+	public constructor(private readonly list: readonly Mark[]) {
 		this.list = list;
 	}
 
@@ -36,11 +33,14 @@ export class MarkQueue {
 			return undefined;
 		}
 
-		const splitMarks = splitMarkForMoveEffects(mark, this.moveEffects);
-		for (let i = splitMarks.length - 1; i > 0; i--) {
-			this.stack.push(splitMarks[i] ?? oob());
+		const splitLength = this.getLengthForSplit(mark);
+		if (splitLength < mark.count) {
+			const [part1, part2] = splitMark(mark, splitLength);
+			this.stack.push(part2);
+			return part1;
 		}
-		return splitMarks[0];
+
+		return mark;
 	}
 
 	/**
@@ -66,4 +66,21 @@ export class MarkQueue {
 		}
 		return mark;
 	}
+
+	protected getLengthForSplit(mark: Mark): number {
+		return mark.count;
+	}
+}
+
+export class MarkQueue extends MarkQueueBase {
+	public constructor(
+		list: readonly Mark[],
+		private readonly moveEffects: MoveEffectTable,
+	) {
+		super(list);
+	}
+
+	protected override getLengthForSplit(mark: Mark): number {
+		return getFirstMoveEffectLength(mark, mark.count, this.moveEffects);
+	}
 }

package/src/feature-libraries/sequence-field/moveEffectTable.ts

@@ -15,7 +15,7 @@ import {
 
 import type { MoveMarkEffect } from "./helperTypes.js";
 import type { CellMark, Detach, Mark, MarkEffect, MoveId, MoveIn, MoveOut } from "./types.js";
-import { isAttachAndDetachEffect, splitMark, splitMarkEffect } from "./utils.js";
+import { isAttachAndDetachEffect, splitMarkEffect } from "./utils.js";
 
 export type MoveEffectTable = CrossFieldManager<MoveEffect>;
 
@@ -168,12 +168,7 @@ function adjustMoveEffectBasis(effect: MoveEffectWithBasis, newBasis: MoveId): M
 	return adjusted;
 }
 
-export function splitMarkForMoveEffects(mark: Mark, effects: MoveEffectTable): Mark[] {
-	const length = getFirstMoveEffectLength(mark, mark.count, effects);
-	return length < mark.count ? splitMark(mark, length) : [mark];
-}
-
-function getFirstMoveEffectLength(
+export function getFirstMoveEffectLength(
 	markEffect: MarkEffect,
 	count: number,
 	effects: MoveEffectTable,

package/src/feature-libraries/sequence-field/sequenceFieldChangeRebaser.ts

@@ -6,12 +6,12 @@
 import type { FieldChangeRebaser } from "../modular-schema/index.js";
 
 import { compose } from "./compose.js";
+import { filterEdits } from "./filterEdits.js";
 import { invert } from "./invert.js";
 import { prune } from "./prune.js";
 import { rebase } from "./rebase.js";
 import { replaceRevisions } from "./replaceRevisions.js";
 import type { Changeset } from "./types.js";
-import { omitMarkEffect } from "./utils.js";
 
 export type SequenceChangeRebaser = FieldChangeRebaser<Changeset>;
 
@@ -21,7 +21,5 @@ export const sequenceFieldChangeRebaser = {
 	rebase,
 	prune,
 	replaceRevisions,
-	mute: (change: Changeset): Changeset => {
-		return change.map((mark) => omitMarkEffect(mark));
-	},
-};
+	filterEdits,
+} as const;

package/src/index.ts

@@ -78,12 +78,14 @@ export {
 	type TreeIdentifierUtils,
 	independentView,
 	type IndependentViewOptions,
+	type IndependentViewTelemetryOptions,
 	createIndependentTreeBeta,
 	createIndependentTreeAlpha,
 	type CreateIndependentTreeAlphaOptions,
 	ForestTypeOptimized,
 	ForestTypeExpensiveDebug,
 	ForestTypeReference,
+	minimize,
 } from "./shared-tree/index.js";
 
 export {
@@ -97,6 +99,7 @@ export {
 	type TreeNodeSchema,
 	TreeViewConfiguration,
 	type ITreeViewConfiguration,
+	type ITreeViewConfigurationAlpha,
 	type ITreeConfigurationOptions,
 	type TreeView,
 	type TreeViewEvents,
@@ -332,6 +335,8 @@ export {
 	type ErasedNode,
 	type ErasedSchemaSubclassable,
 	type SnapshotSchemaCompatibilityOptions,
+	StagedSchemaUpgradePolicy,
+	type StagedSchemaUpgradePolicyFactory,
 	type ArrayPlaceAnchor,
 	createArrayInsertionAnchor,
 	type WithValue,
@@ -415,3 +420,4 @@ export {
 	utf16LengthForCodePoints,
 } from "./text/index.js";
 export { ExtensibleUnionNode } from "./extensibleUnionNode.js";
+export { Component } from "./componentApi.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.111.0";
+export const pkgVersion = "2.113.0-411909";

package/src/shared-tree/independentView.ts

@@ -3,12 +3,16 @@
  * Licensed under the MIT License.
  */
 
-import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import type { IFluidHandle, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import {
 	type IIdCompressor,
 	createIdCompressor,
 } from "@fluidframework/id-compressor/internal";
+import {
+	createChildLogger,
+	extractTelemetryLoggerExt,
+} from "@fluidframework/telemetry-utils/internal";
 
 import type { CodecWriteOptions, ICodecOptions } from "../codec/index.js";
 import {
@@ -22,8 +26,8 @@ import {
 	FieldBatchDecodingContext,
 	defaultIncrementalEncodingPolicy,
 	schemaCodecBuilder,
+	combineChunks,
 } from "../feature-libraries/index.js";
-import { combineChunks } from "../feature-libraries/index.js";
 import type {
 	TreeViewConfiguration,
 	ImplicitFieldSchema,
@@ -52,11 +56,28 @@ import {
 } from "./sharedTree.js";
 import { createTreeCheckout } from "./treeCheckout.js";
 
+/**
+ * Options for supplying a telemetry logger to an independent tree view.
+ * @remarks
+ * Events emitted by the independent tree are tagged with the `independentView` namespace.
+ * If no logger is provided, telemetry events are dropped.
+ * @alpha @input
+ */
+export interface IndependentViewTelemetryOptions {
+	/**
+	 * Optional logger for telemetry.
+	 */
+	readonly logger?: ITelemetryBaseLogger | undefined;
+}
+
 /**
  * {@link independentView} options.
  * @alpha @input
  */
-export interface IndependentViewOptions extends ForestOptions, Partial<CodecWriteOptions> {
+export interface IndependentViewOptions
+	extends ForestOptions,
+		Partial<CodecWriteOptions>,
+		IndependentViewTelemetryOptions {
 	/**
 	 * Optional ID compressor for generating and compressing identifiers.
 	 * If not provided, a new one will be created.
@@ -69,6 +90,7 @@ export interface IndependentViewOptions extends ForestOptions, Partial<CodecWrit
  * @alpha
  */
 export type CreateIndependentTreeAlphaOptions = ForestOptions &
+	IndependentViewTelemetryOptions &
 	(
 		| (IndependentViewOptions & {
 				/**
@@ -120,7 +142,7 @@ export function independentView<const TSchema extends ImplicitFieldSchema>(
  */
 export function independentInitializedView<const TSchema extends ImplicitFieldSchema>(
 	config: TreeViewConfiguration<TSchema>,
-	options: ForestOptions & ICodecOptions,
+	options: ForestOptions & ICodecOptions & IndependentViewTelemetryOptions,
 	content: ViewContent,
 ): TreeViewAlpha<TSchema> {
 	return createIndependentTreeAlpha({ ...options, content }).viewWith(
@@ -202,7 +224,13 @@ export function createIndependentTreeBeta<const TSchema extends ImplicitFieldSch
 export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSchema>(
 	options?: CreateIndependentTreeAlphaOptions,
 ): ViewableTree & Pick<ITreeAlpha, "exportVerbose" | "exportSimpleSchema"> {
-	const breaker = new Breakable("independentView");
+	const logger = extractTelemetryLoggerExt(
+		createChildLogger({
+			logger: options?.logger,
+			namespace: "independentView",
+		}),
+	);
+	const breaker = new Breakable("independentView", logger);
 	const idCompressor: IIdCompressor =
 		options?.idCompressor ?? options?.content?.idCompressor ?? createIdCompressor();
 	const mintRevisionTag = (): RevisionTag => idCompressor.generateCompressedId();
@@ -223,6 +251,7 @@ export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSc
 		forest,
 		schema: schemaRepository,
 		breaker,
+		logger,
 		codecOptions: options,
 	});
 
@@ -235,6 +264,7 @@ export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSc
 		// (finalized compressed ids or strings), so summary-style decode is correct.
 		const context = FieldBatchDecodingContext.forSummary({
 			idCompressor,
+			healing: undefined,
 		});
 		const fieldCursors = fieldBatchCodec.decode(
 			options.content.tree as JsonCompatibleReadOnly,

package/src/shared-tree/index.ts

@@ -43,6 +43,8 @@ export type {
 	SharedTreeEditBuilder,
 } from "./sharedTreeEditBuilder.js";
 
+export { minimize } from "./transactionMinimize.js";
+
 export { Tree } from "./tree.js";
 export type { RunTransaction } from "./tree.js";
 
@@ -57,6 +59,7 @@ export {
 	type ViewContent,
 	independentView,
 	type IndependentViewOptions,
+	type IndependentViewTelemetryOptions,
 	createIndependentTreeBeta,
 	createIndependentTreeAlpha,
 	type CreateIndependentTreeAlphaOptions,

package/src/shared-tree/schematizingTreeView.ts

@@ -23,6 +23,7 @@ import {
 	type FlexTreeUnknownUnboxed,
 	FieldKinds,
 	type FlexTreeRequiredField,
+	allowsRepoSuperset,
 } from "../feature-libraries/index.js";
 import {
 	type ImplicitFieldSchema,
@@ -32,8 +33,9 @@ import {
 	tryGetTreeNodeForField,
 	setField,
 	normalizeFieldSchema,
-	SchemaCompatibilityTester,
+	checkSchemaCompatibility,
 	type InsertableContent,
+	type StagedSchemaUpgradePolicy,
 	type TreeViewConfiguration,
 	type TreeViewAlpha,
 	type InsertableField,
@@ -57,6 +59,7 @@ import {
 	toInitialSchema,
 	toUpgradeSchema,
 	type TreeBranchAlpha,
+	type TreeSchema,
 } from "../simple-tree/index.js";
 import {
 	type Breakable,
@@ -98,7 +101,14 @@ export class SchematizingSimpleTreeView<
 		IEmitter<TreeViewEvents & TreeBranchEvents> &
 		HasListeners<TreeViewEvents & TreeBranchEvents> = createEmitter();
 
-	private readonly viewSchema: SchemaCompatibilityTester;
+	/**
+	 * The schema for this view, captured at construction time for compatibility checking.
+	 */
+	private readonly viewSchema: TreeSchema;
+	/**
+	 * Stored-schema generation policy from the view configuration, frozen at construction time.
+	 */
+	private readonly stagedUpgradePolicy: StagedSchemaUpgradePolicy;
 
 	/**
 	 * Events to unregister upon flex-tree view disposal.
@@ -141,9 +151,18 @@ export class SchematizingSimpleTreeView<
 
 		this.rootFieldSchema = normalizeFieldSchema(config.schema);
 
-		const configAlpha = new TreeViewConfigurationAlpha({ schema: config.schema });
+		const stagedUpgradePolicy =
+			config instanceof TreeViewConfigurationAlpha ? config.stagedUpgradePolicy : undefined;
+		const configAlpha = new TreeViewConfigurationAlpha({
+			schema: config.schema,
+			enableSchemaValidation: config.enableSchemaValidation,
+			preventAmbiguity: config.preventAmbiguity,
+			stagedUpgradePolicy,
+		});
+		this.stagedUpgradePolicy = configAlpha.stagedUpgradePolicy;
 
-		this.viewSchema = new SchemaCompatibilityTester(configAlpha);
+		// Store viewSchema directly from the configuration (TreeViewConfigurationAlpha implements TreeSchema)
+		this.viewSchema = configAlpha;
 		// This must be initialized before `update` can be called.
 		this.currentCompatibility = {
 			canView: false,
@@ -188,7 +207,7 @@ export class SchematizingSimpleTreeView<
 		}
 
 		this.runSchemaEdit(() => {
-			const schema = toInitialSchema(this.config.schema);
+			const schema = toInitialSchema(this.config.schema, this.stagedUpgradePolicy);
 			// This has to be the contextless version, since when "initialize" is called (right after this),
 			// it will do a schema change which would dispose of the current context (see inside `update`).
 			// Thus using the current context (if any) would hydrate nodes then
@@ -246,19 +265,18 @@ export class SchematizingSimpleTreeView<
 	public upgradeSchema(): void {
 		this.ensureUndisposed();
 
-		const compatibility = this.compatibility;
-		if (compatibility.isEquivalent) {
-			// No-op
-			return;
-		}
-
-		if (!compatibility.canUpgrade) {
+		const newSchema = toUpgradeSchema(this.viewSchema.root, this.stagedUpgradePolicy);
+		const storedSchema = this.checkout.storedSchema.clone();
+		if (!allowsRepoSuperset(defaultSchemaPolicy, storedSchema, newSchema)) {
 			throw new UsageError(
-				"Existing stored schema cannot be upgraded (see TreeView.compatibility.canUpgrade).",
+				"Existing stored schema cannot be upgraded to the requested schema (see TreeView.compatibility.canUpgrade).",
 			);
 		}
+		if (allowsRepoSuperset(defaultSchemaPolicy, newSchema, storedSchema)) {
+			// No-op
+			return;
+		}
 
-		const newSchema = toUpgradeSchema(this.viewSchema.viewSchema.root);
 		this.runSchemaEdit(() => this.checkout.updateSchema(newSchema));
 	}
 
@@ -347,12 +365,8 @@ export class SchematizingSimpleTreeView<
 	private update(): void {
 		this.disposeFlexView();
 
-		const compatibility = this.viewSchema.checkCompatibility(this.checkout.storedSchema);
-
-		this.currentCompatibility = {
-			...compatibility,
-			canInitialize: canInitialize(this.checkout),
-		};
+		const compatibility = this.computeCompatibility();
+		this.currentCompatibility = compatibility;
 
 		const anchors = this.checkout.forest.anchors;
 		const slots = anchors.slots;
@@ -423,6 +437,18 @@ export class SchematizingSimpleTreeView<
 		}
 	}
 
+	private computeCompatibility(): SchemaCompatibilityStatus {
+		const compatibility = checkSchemaCompatibility(
+			this.viewSchema,
+			this.checkout.storedSchema,
+			this.stagedUpgradePolicy,
+		);
+		return {
+			...compatibility,
+			canInitialize: canInitialize(this.checkout),
+		};
+	}
+
 	private runSchemaEdit(edit: () => void): void {
 		this.midUpgrade = true;
 		try {
@@ -533,5 +559,11 @@ export class SchematizingSimpleTreeView<
 		return this.checkout.isMissingEditsFrom(context);
 	}
 
+	public computeNetChangeIfRebasedOnto(
+		context: TreeBranchAlpha,
+	): JsonCompatibleReadOnly | undefined {
+		return this.checkout.computeNetChangeIfRebasedOnto(context);
+	}
+
 	// #endregion Branching
 }

package/src/shared-tree/serializedChange.ts

@@ -0,0 +1,127 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
+import { isStableId } from "@fluidframework/id-compressor/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import {
+	type ChangeFamily,
+	type RevisionTag,
+	tagChange,
+	type ChangeEncodingContext,
+	type TaggedChange,
+} from "../core/index.js";
+import type { JsonCompatibleReadOnly } from "../util/index.js";
+
+import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
+import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
+import { SharedTreeChangeFormatVersion } from "./sharedTreeChangeCodecs.js";
+
+/**
+ * Represents a serialized change for SharedTree.
+ *
+ * Data in this format is not expected to be durable beyond the scope of a single session.
+ */
+interface SerializedChange {
+	readonly version: 1;
+	readonly revision: RevisionTag;
+	readonly change: JsonCompatibleReadOnly;
+	readonly originatorId: SessionId;
+}
+
+function isSerializedChangeV1(value: unknown): value is SerializedChange {
+	if (typeof value !== "object" || value === null) {
+		return false;
+	}
+	const change = value as Partial<SerializedChange>;
+	return (
+		change.version === 1 &&
+		(change.revision === "root" || typeof change.revision === "number") &&
+		typeof change.originatorId === "string" &&
+		isStableId(change.originatorId) &&
+		change.change !== undefined
+	);
+}
+
+function encodeSerializedChangeV1(
+	idCompressor: IIdCompressor,
+	changeFamily: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>,
+	change: SharedTreeChange,
+	changeRevision: RevisionTag,
+	contextRevision?: RevisionTag,
+): JsonCompatibleReadOnly {
+	const context: ChangeEncodingContext = {
+		idCompressor,
+		originatorId: idCompressor.localSessionId,
+		revision: contextRevision,
+		isSummary: false,
+	};
+	const encodedChange = changeFamily.codecs
+		.resolve(SharedTreeChangeFormatVersion.v4)
+		.encode(change, context);
+
+	return {
+		version: 1,
+		revision: changeRevision,
+		originatorId: idCompressor.localSessionId,
+		change: encodedChange,
+	} satisfies SerializedChange;
+}
+
+function decodeSerializedChangeV1(
+	idCompressor: IIdCompressor,
+	changeFamily: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>,
+	serializedChange: JsonCompatibleReadOnly,
+): TaggedChange<SharedTreeChange> {
+	if (!isSerializedChangeV1(serializedChange)) {
+		throw new UsageError(`Cannot apply change. Invalid serialized change format.`);
+	}
+	const { revision, originatorId, change } = serializedChange;
+	if (originatorId !== idCompressor.localSessionId) {
+		throw new UsageError(
+			`Cannot apply change. A serialized changed must be applied to the same SharedTree as it was created from.`,
+		);
+	}
+	const context: ChangeEncodingContext = {
+		idCompressor,
+		originatorId: idCompressor.localSessionId,
+		revision,
+		isSummary: false,
+	};
+	const treeChange = changeFamily.codecs
+		.resolve(SharedTreeChangeFormatVersion.v4)
+		.decode(change, context);
+	return tagChange(treeChange, revision);
+}
+
+/**
+ * Provides utilities for serializing and deserializing SharedTree changes.
+ *
+ * @remarks Such changes are not expected to be durable beyond the scope of a single session.
+ */
+export const SerializedChange = {
+	/** Utilities for version 1 of the serialized change format. */
+	V1: {
+		/**
+		 * Encodes a SharedTree change into the version 1 serialized change format.
+		 * @param idCompressor - The ID compressor to use for encoding.
+		 * @param changeFamily - The change family to use for encoding.
+		 * @param change - The change to encode.
+		 * @param changeRevision - The revision tag for the change.
+		 * @param contextRevision - The optional context revision tag.
+		 * @returns The encoded change in the version 1 serialized change format.
+		 */
+		encode: encodeSerializedChangeV1,
+		/**
+		 * Decodes a version 1 serialized change into a SharedTree change.
+		 * @param idCompressor - The ID compressor to use for decoding.
+		 * @param changeFamily - The change family to use for decoding.
+		 * @param serializedChange - The serialized change to decode.
+		 * @returns The decoded SharedTree change.
+		 */
+		decode: decodeSerializedChangeV1,
+	},
+} as const;