@fluidframework/tree 2.110.0 → 2.112.0

package/src/feature-libraries/schemaChecker.ts

@@ -32,13 +32,82 @@ export enum SchemaValidationError {
 	Node_MissingSchema,
 }
 
+/**
+ * Additional context about a schema validation error.
+ * @remarks
+ * Not all fields are populated for every error type — only those relevant to the specific error.
+ */
+export interface SchemaValidationErrorContext {
+	/**
+	 * The type identifier of the node that failed validation.
+	 */
+	readonly nodeType?: string;
+	/**
+	 * The set of type identifiers allowed in the field, if applicable.
+	 */
+	readonly allowedTypes?: ReadonlySet<string>;
+	/**
+	 * Field keys on the node that were not recognized by its schema.
+	 */
+	readonly unexpectedFields?: ReadonlySet<string>;
+}
+
 /**
  * Throws a UsageError indicating a tree is out of schema.
  */
-export function throwOutOfSchema(maybeError: SchemaValidationError): never {
-	throw new UsageError(
-		`Tree does not conform to schema: ${SchemaValidationError[maybeError]}`,
-	);
+export function throwOutOfSchema(
+	maybeError: SchemaValidationError,
+	context?: SchemaValidationErrorContext,
+): never {
+	throw new UsageError(formatSchemaValidationError(maybeError, context));
+}
+
+// Not exported: internal helper used by throwOutOfSchema.
+function formatSchemaValidationError(
+	error: SchemaValidationError,
+	context: SchemaValidationErrorContext | undefined,
+): string {
+	switch (error) {
+		case SchemaValidationError.Field_NodeTypeNotAllowed: {
+			const nodeDesc = context?.nodeType === undefined ? "unknown" : `"${context.nodeType}"`;
+			const allowedDesc =
+				context?.allowedTypes === undefined
+					? "unknown"
+					: `[${[...context.allowedTypes].map((t) => `"${t}"`).join(", ")}]`;
+			return (
+				`Tree does not conform to schema. ` +
+				`A node of type ${nodeDesc} is not allowed in this field. Allowed types: ${allowedDesc}. ` +
+				`If using a staged allowed type, the stored schema has not been upgraded to include this type yet. ` +
+				`Either upgrade the schema to enable the staged type or avoid inserting content of this type until the schema is upgraded.`
+			);
+		}
+		case SchemaValidationError.Node_MissingSchema: {
+			const nodeDesc = context?.nodeType === undefined ? "unknown" : `"${context.nodeType}"`;
+			return (
+				`Tree does not conform to schema. ` +
+				`No schema definition was found for node type ${nodeDesc}. ` +
+				`Ensure the node's type is included in the schema and that the stored schema has been upgraded if needed.`
+			);
+		}
+		case SchemaValidationError.ObjectNode_FieldNotInSchema: {
+			const nodeDesc = context?.nodeType === undefined ? "unknown" : `"${context.nodeType}"`;
+			const fieldsDesc =
+				context?.unexpectedFields === undefined || context.unexpectedFields.size === 0
+					? undefined
+					: `[${[...context.unexpectedFields].map((f) => `"${f}"`).join(", ")}]`;
+			const fieldsPart =
+				fieldsDesc === undefined
+					? "The node has fields that are not defined in its schema."
+					: `Unexpected fields: ${fieldsDesc}.`;
+			return (
+				`Tree does not conform to schema. ` +
+				`A node of type ${nodeDesc} has fields not defined in its schema. ${fieldsPart}`
+			);
+		}
+		default: {
+			return `Tree does not conform to schema: ${SchemaValidationError[error]}.`;
+		}
+	}
 }
 
 type NotUndefined = number | string | boolean | bigint | symbol | object;
@@ -53,12 +122,14 @@ type NotUndefined = number | string | boolean | bigint | symbol | object;
 export function isNodeInSchema<T extends NotUndefined>(
 	node: MinimalMapTreeNodeView,
 	schemaAndPolicy: SchemaAndPolicy,
-	onError: (error: SchemaValidationError) => T,
+	onError: (error: SchemaValidationError, context?: SchemaValidationErrorContext) => T,
 ): T | undefined {
 	// Validate the schema declared by the node exists
 	const schema = schemaAndPolicy.schema.nodeSchema.get(node.type);
 	if (schema === undefined) {
-		return onError(SchemaValidationError.Node_MissingSchema);
+		return onError(SchemaValidationError.Node_MissingSchema, {
+			nodeType: node.type,
+		});
 	}
 
 	// Validate the node is well formed according to its schema
@@ -95,7 +166,10 @@ export function isNodeInSchema<T extends NotUndefined>(
 			// Code using this with a stored schema derived from a view schema rather than the document can be problematic because it may be missing unknown fields that the actual document has.
 			// Other schema evolution features like "staged" allowed types will likely cause similar issues elsewhere in this checker.
 			if (uncheckedFieldsFromNode.size > 0) {
-				return onError(SchemaValidationError.ObjectNode_FieldNotInSchema);
+				return onError(SchemaValidationError.ObjectNode_FieldNotInSchema, {
+					nodeType: node.type,
+					unexpectedFields: uncheckedFieldsFromNode,
+				});
 			}
 		} else if (schema instanceof MapNodeStoredSchema) {
 			for (const [_key, field] of node.fields) {
@@ -128,7 +202,7 @@ export function isFieldInSchema<T extends NotUndefined>(
 	childNodes: MapTreeFieldViewGeneric<MinimalMapTreeNodeView>,
 	schema: TreeFieldStoredSchema,
 	schemaAndPolicy: SchemaAndPolicy,
-	onError: (error: SchemaValidationError) => T,
+	onError: (error: SchemaValidationError, context?: SchemaValidationErrorContext) => T,
 ): T | undefined {
 	// Validate that the field kind is handled by the schema policy
 	const kind = schemaAndPolicy.policy.fieldKinds.get(schema.kind);
@@ -147,7 +221,10 @@ export function isFieldInSchema<T extends NotUndefined>(
 	for (const node of childNodes) {
 		// Validate the type declared by the node is allowed in this field
 		if (schema.types !== undefined && !schema.types.has(node.type)) {
-			return onError(SchemaValidationError.Field_NodeTypeNotAllowed);
+			return onError(SchemaValidationError.Field_NodeTypeNotAllowed, {
+				nodeType: node.type,
+				allowedTypes: schema.types,
+			});
 		}
 
 		// Validate the node complies with the type it declares to be.

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 {
@@ -273,17 +275,21 @@ export {
 	type NodeSchemaMetadata,
 	type SchemaStatics,
 	type ITreeAlpha,
+	type NoChangeConstraint,
+	type NodeInDocumentConstraint,
+	type RunTransactionParamsAlpha,
+	type RunTransactionParamsBeta,
+	type TransactionCallbackStatusAlpha,
+	type TransactionCallbackStatusBeta,
 	type TransactionConstraint,
 	type TransactionConstraintAlpha,
-	type NodeInDocumentConstraint,
-	type NoChangeConstraint,
-	type RunTransactionParams,
-	type VoidTransactionCallbackStatus,
-	type TransactionCallbackStatus,
-	type TransactionResult,
-	type TransactionResultExt,
-	type TransactionResultSuccess,
+	type TransactionPostProcessor,
 	type TransactionResultFailed,
+	type TransactionResultSuccess,
+	type TransactionValueResult,
+	type TransactionVoidResult,
+	type VoidTransactionCallbackStatusAlpha,
+	type VoidTransactionCallbackStatusBeta,
 	rollback,
 	generateSchemaFromSimpleSchema,
 	evaluateLazySchema,
@@ -406,7 +412,9 @@ export { asAlpha, asBeta } from "./api.js";
 export {
 	TextAsTree,
 	FormattedTextAsTree,
+	FormattedTextAsTreeDefault,
 	codePointCount,
 	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.110.0";
+export const pkgVersion = "2.112.0";

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 {
@@ -19,13 +23,11 @@ import {
 import {
 	createNodeIdentifierManager,
 	fieldBatchCodecBuilder,
-	type FieldBatchEncodingContext,
-	defaultSchemaPolicy,
-	TreeCompressionStrategy,
+	FieldBatchDecodingContext,
 	defaultIncrementalEncodingPolicy,
 	schemaCodecBuilder,
+	combineChunks,
 } from "../feature-libraries/index.js";
-import { combineChunks } from "../feature-libraries/index.js";
 import type {
 	TreeViewConfiguration,
 	ImplicitFieldSchema,
@@ -54,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.
@@ -71,6 +90,7 @@ export interface IndependentViewOptions extends ForestOptions, Partial<CodecWrit
  * @alpha
  */
 export type CreateIndependentTreeAlphaOptions = ForestOptions &
+	IndependentViewTelemetryOptions &
 	(
 		| (IndependentViewOptions & {
 				/**
@@ -122,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(
@@ -204,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();
@@ -225,6 +251,7 @@ export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSc
 		forest,
 		schema: schemaRepository,
 		breaker,
+		logger,
 		codecOptions: options,
 	});
 
@@ -233,14 +260,12 @@ export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSc
 		const fieldBatchCodec = fieldBatchCodecBuilder.buildDecoder(options);
 		const newSchema = schemaCodec.decode(options.content.schema);
 
-		const context: FieldBatchEncodingContext = {
-			encodeType: TreeCompressionStrategy.Compressed,
+		// TreeAlpha.exportCompressed encodes this payload in originatorless-safe form
+		// (finalized compressed ids or strings), so summary-style decode is correct.
+		const context = FieldBatchDecodingContext.forSummary({
 			idCompressor,
-			originatorId: idCompressor.localSessionId, // Is this right? If so, why is is needed?
-			schema: { schema: newSchema, policy: defaultSchemaPolicy },
-			// Not a summary blob — this is a synthetic decode of inline content.
-			isSummary: false,
-		};
+			healing: undefined,
+		});
 		const fieldCursors = fieldBatchCodec.decode(
 			options.content.tree as JsonCompatibleReadOnly,
 			context,

package/src/shared-tree/index.ts

@@ -30,6 +30,7 @@ export {
 	TreeCheckout,
 	type ITreeCheckout,
 	type CheckoutEvents,
+	type TreeTransactor,
 } from "./treeCheckout.js";
 
 export { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
@@ -42,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";
 
@@ -56,6 +59,7 @@ export {
 	type ViewContent,
 	independentView,
 	type IndependentViewOptions,
+	type IndependentViewTelemetryOptions,
 	createIndependentTreeBeta,
 	createIndependentTreeAlpha,
 	type CreateIndependentTreeAlphaOptions,

package/src/shared-tree/schematizingTreeView.ts

@@ -32,7 +32,7 @@ import {
 	tryGetTreeNodeForField,
 	setField,
 	normalizeFieldSchema,
-	SchemaCompatibilityTester,
+	checkSchemaCompatibility,
 	type InsertableContent,
 	type TreeViewConfiguration,
 	type TreeViewAlpha,
@@ -41,11 +41,11 @@ import {
 	type ReadSchema,
 	type UnsafeUnknownSchema,
 	type TreeBranchEvents,
-	type VoidTransactionCallbackStatus,
-	type TransactionCallbackStatus,
-	type TransactionResult,
-	type TransactionResultExt,
-	type RunTransactionParams,
+	type VoidTransactionCallbackStatusAlpha,
+	type TransactionCallbackStatusAlpha,
+	type TransactionVoidResult,
+	type TransactionValueResult,
+	type RunTransactionParamsAlpha,
 	HydratedContext,
 	SimpleContextSlot,
 	areImplicitFieldSchemaEqual,
@@ -57,6 +57,7 @@ import {
 	toInitialSchema,
 	toUpgradeSchema,
 	type TreeBranchAlpha,
+	type TreeSchema,
 } from "../simple-tree/index.js";
 import {
 	type Breakable,
@@ -98,7 +99,7 @@ export class SchematizingSimpleTreeView<
 		IEmitter<TreeViewEvents & TreeBranchEvents> &
 		HasListeners<TreeViewEvents & TreeBranchEvents> = createEmitter();
 
-	private readonly viewSchema: SchemaCompatibilityTester;
+	private readonly viewSchema: TreeSchema;
 
 	/**
 	 * Events to unregister upon flex-tree view disposal.
@@ -143,7 +144,7 @@ export class SchematizingSimpleTreeView<
 
 		const configAlpha = new TreeViewConfigurationAlpha({ schema: config.schema });
 
-		this.viewSchema = new SchemaCompatibilityTester(configAlpha);
+		this.viewSchema = configAlpha;
 		// This must be initialized before `update` can be called.
 		this.currentCompatibility = {
 			canView: false,
@@ -258,7 +259,7 @@ export class SchematizingSimpleTreeView<
 			);
 		}
 
-		const newSchema = toUpgradeSchema(this.viewSchema.viewSchema.root);
+		const newSchema = toUpgradeSchema(this.viewSchema.root);
 		this.runSchemaEdit(() => this.checkout.updateSchema(newSchema));
 	}
 
@@ -272,40 +273,40 @@ export class SchematizingSimpleTreeView<
 	}
 
 	public runTransaction<TSuccessValue, TFailureValue>(
-		transaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,
-		params?: RunTransactionParams,
-	): TransactionResultExt<TSuccessValue, TFailureValue>;
+		transaction: () => TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue>,
+		params?: RunTransactionParamsAlpha,
+	): TransactionValueResult<TSuccessValue, TFailureValue>;
 	public runTransaction(
-		transaction: () => VoidTransactionCallbackStatus | void,
-		params?: RunTransactionParams,
-	): TransactionResult;
+		transaction: () => VoidTransactionCallbackStatusAlpha | void,
+		params?: RunTransactionParamsAlpha,
+	): TransactionVoidResult;
 	public runTransaction<TSuccessValue, TFailureValue>(
 		transaction: () =>
-			| TransactionCallbackStatus<TSuccessValue, TFailureValue>
-			| VoidTransactionCallbackStatus
+			| TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue>
+			| VoidTransactionCallbackStatusAlpha
 			| void,
-		params?: RunTransactionParams,
-	): TransactionResultExt<TSuccessValue, TFailureValue> | TransactionResult {
+		params?: RunTransactionParamsAlpha,
+	): TransactionValueResult<TSuccessValue, TFailureValue> | TransactionVoidResult {
 		this.ensureUndisposed();
 		return this.checkout.runTransaction(transaction, params);
 	}
 
 	public runTransactionAsync<TSuccessValue, TFailureValue>(
-		transaction: () => Promise<TransactionCallbackStatus<TSuccessValue, TFailureValue>>,
-		params?: RunTransactionParams,
-	): Promise<TransactionResultExt<TSuccessValue, TFailureValue>>;
+		transaction: () => Promise<TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue>>,
+		params?: RunTransactionParamsAlpha,
+	): Promise<TransactionValueResult<TSuccessValue, TFailureValue>>;
 	public runTransactionAsync(
-		transaction: () => Promise<VoidTransactionCallbackStatus | void>,
-		params?: RunTransactionParams,
-	): Promise<TransactionResult>;
+		transaction: () => Promise<VoidTransactionCallbackStatusAlpha | void>,
+		params?: RunTransactionParamsAlpha,
+	): Promise<TransactionVoidResult>;
 	public async runTransactionAsync<TSuccessValue, TFailureValue>(
 		transaction: () => Promise<
-			| TransactionCallbackStatus<TSuccessValue, TFailureValue>
-			| VoidTransactionCallbackStatus
+			| TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue>
+			| VoidTransactionCallbackStatusAlpha
 			| void
 		>,
-		params: RunTransactionParams | undefined,
-	): Promise<TransactionResultExt<TSuccessValue, TFailureValue> | TransactionResult> {
+		params: RunTransactionParamsAlpha | undefined,
+	): Promise<TransactionValueResult<TSuccessValue, TFailureValue> | TransactionVoidResult> {
 		this.ensureUndisposed();
 		if (this.checkout.transaction.size > 0) {
 			// breaker.break() sets brokenBy synchronously before throwing.
@@ -347,7 +348,10 @@ export class SchematizingSimpleTreeView<
 	private update(): void {
 		this.disposeFlexView();
 
-		const compatibility = this.viewSchema.checkCompatibility(this.checkout.storedSchema);
+		const compatibility = checkSchemaCompatibility(
+			this.viewSchema,
+			this.checkout.storedSchema,
+		);
 
 		this.currentCompatibility = {
 			...compatibility,
@@ -533,5 +537,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;