@fluidframework/tree 2.53.1 → 2.60.0

package/src/codec/codec.ts

@@ -3,12 +3,14 @@
  * Licensed under the MIT License.
  */
 
+import type { ErasedType } from "@fluidframework/core-interfaces/internal";
 import { IsoBuffer, bufferToString } from "@fluid-internal/client-utils";
 import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { Static, TAnySchema, TSchema } from "@sinclair/typebox";
 
 import type { ChangeEncodingContext } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
+import { noopValidator } from "./noopValidator.js";
 
 /**
  * Translates decoded data to encoded data.
@@ -44,6 +46,46 @@ export interface SchemaValidationFunction<Schema extends TSchema> {
 	check(data: unknown): data is Static<Schema>;
 }
 
+/**
+ * A kind of validator for SharedTree's internal data formats.
+ * @remarks
+ * Assuming no data corruption or type confusion, such validation should never fail.
+ * Any client version compatibility issues should instead be detected by the data format versioning which Shared Tree does internally independent of data format validation.
+ * However, persisted data can sometimes be corrupted, bugs can produce invalid data, or users can mix up which data is compatible with which APIs.
+ * In such cases, a format validator can help catch issues.
+ *
+ * Current options are {@link FormatValidatorNoOp} and {@link FormatValidatorBasic}.
+ * @privateRemarks
+ * Implement using {@link toFormatValidator}.
+ * Consume using {@link extractJsonValidator}.
+ *
+ * Exposing this as the stable API entry point (instead of {@link JsonValidator}) means that we avoid leaking the reference to TypeBox to the API surface.
+ * Additionally, if we adopt non JSON formats, we can just update the validators as needed without breaking the API.
+ * This also allows us to avoid stabilizing or documenting how handles interact with JSON validation since that is not exposed through this type.
+ * @sealed @alpha
+ */
+export interface FormatValidator extends ErasedType<"FormatValidator"> {}
+
+/**
+ * A {@link FormatValidator} which does no validation.
+ * @alpha
+ */
+export const FormatValidatorNoOp = toFormatValidator(noopValidator);
+
+/**
+ * Type erase a {@link JsonValidator} to a {@link FormatValidator}.
+ */
+export function toFormatValidator(factory: JsonValidator): FormatValidator {
+	return factory as unknown as FormatValidator;
+}
+
+/**
+ * Un-type-erase the {@link FormatValidator}.
+ */
+export function extractJsonValidator(input: FormatValidator | JsonValidator): JsonValidator {
+	return input as unknown as JsonValidator;
+}
+
 /**
  * JSON schema validator compliant with draft 6 schema. See https://json-schema.org.
  * @alpha @input
@@ -69,19 +111,22 @@ export interface JsonValidator {
  */
 export interface ICodecOptions {
 	/**
-	 * {@link JsonValidator} which SharedTree uses to validate persisted data it reads & writes
+	 * {@link FormatValidator} which SharedTree uses to validate persisted data it reads & writes
 	 * matches the expected encoded format (i.e. the wire format for ops and summaries).
-	 *
-	 * See {@link noopValidator} and {@link typeboxValidator} for out-of-the-box implementations.
+	 * @remarks
+	 * See {@link FormatValidatorNoOp} and {@link FormatValidatorBasic} for out-of-the-box implementations.
 	 *
 	 * This option is not "on-by-default" because JSON schema validation comes with a small but noticeable
 	 * runtime performance cost, and popular schema validation libraries have relatively large bundle size.
 	 *
-	 * SharedTree users are still encouraged to use a non-trivial validator (i.e. not `noopValidator`)
+	 * SharedTree users are still encouraged to use a non-trivial validator (i.e. not `FormatValidatorNoOp`)
 	 * whenever reasonable: it gives better fail-fast behavior when unexpected encoded data is found,
 	 * which reduces the risk of unrecoverable data corruption.
+	 *
+	 * Use of {@link JsonValidator} here is deprecated and will be removed:
+	 * it is recommended to use {@link FormatValidator} instead.
 	 */
-	readonly jsonValidator: JsonValidator;
+	readonly jsonValidator: JsonValidator | FormatValidator;
 }
 
 /**
@@ -326,12 +371,12 @@ export function withSchemaValidation<
 >(
 	schema: EncodedSchema,
 	codec: IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate, TContext>,
-	validator?: JsonValidator,
+	validator?: JsonValidator | FormatValidator,
 ): IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate, TContext> {
 	if (!validator) {
 		return codec;
 	}
-	const compiledFormat = validator.compile(schema);
+	const compiledFormat = extractJsonValidator(validator).compile(schema);
 	return {
 		encode: (obj: TInMemoryFormat, context: TContext): TEncodedFormat => {
 			const encoded = codec.encode(obj, context);

package/src/codec/index.ts

@@ -21,6 +21,10 @@ export {
 	withSchemaValidation,
 	FluidClientVersion,
 	currentVersion,
+	toFormatValidator,
+	FormatValidatorNoOp,
+	type FormatValidator,
+	extractJsonValidator,
 } from "./codec.js";
 export {
 	DiscriminatedUnionDispatcher,

package/src/external-utilities/index.ts

@@ -3,4 +3,4 @@
  * Licensed under the MIT License.
  */
 
-export { typeboxValidator } from "./typeboxValidator.js";
+export { typeboxValidator, FormatValidatorBasic } from "./typeboxValidator.js";

package/src/external-utilities/typeboxValidator.ts

@@ -8,7 +8,7 @@ import type { Static, TSchema } from "@sinclair/typebox";
 // eslint-disable-next-line import/no-internal-modules
 import { TypeCompiler } from "@sinclair/typebox/compiler";
 
-import type { JsonValidator } from "../codec/index.js";
+import { toFormatValidator, type JsonValidator } from "../codec/index.js";
 
 /**
  * A {@link JsonValidator} implementation which uses TypeBox's JSON schema validator.
@@ -29,3 +29,9 @@ export const typeboxValidator: JsonValidator = {
 		};
 	},
 };
+
+/**
+ * A {@link FormatValidator} implementation which uses TypeBox's JSON schema validator.
+ * @alpha
+ */
+export const FormatValidatorBasic = toFormatValidator(typeboxValidator);

package/src/feature-libraries/chunked-forest/codec/chunkDecoding.ts

@@ -17,7 +17,7 @@ import type {
 	Value,
 	TreeChunk,
 } from "../../../core/index.js";
-import { assertValidIndex } from "../../../util/index.js";
+import { assertValidIndex, brand } from "../../../util/index.js";
 import { BasicChunk } from "../basicChunk.js";
 import { emptyChunk } from "../emptyChunk.js";
 import { SequenceChunk } from "../sequenceChunk.js";
@@ -41,12 +41,14 @@ import {
 	type EncodedAnyShape,
 	type EncodedChunkShape,
 	type EncodedFieldBatch,
+	type EncodedIncrementalChunkShape,
 	type EncodedInlineArrayShape,
 	type EncodedNestedArrayShape,
 	type EncodedNodeShape,
 	type EncodedValueShape,
 	SpecialField,
 } from "./format.js";
+import type { IncrementalDecoder } from "./codecs.js";
 
 export interface IdDecodingContext {
 	idCompressor: IIdCompressor;
@@ -61,10 +63,11 @@ export interface IdDecodingContext {
 export function decode(
 	chunk: EncodedFieldBatch,
 	idDecodingContext: { idCompressor: IIdCompressor; originatorId: SessionId },
+	incrementalDecoder?: IncrementalDecoder,
 ): TreeChunk[] {
 	return genericDecode(
 		decoderLibrary,
-		new DecoderContext(chunk.identifiers, chunk.shapes, idDecodingContext),
+		new DecoderContext(chunk.identifiers, chunk.shapes, idDecodingContext, incrementalDecoder),
 		chunk,
 		anyDecoder,
 	);
@@ -87,6 +90,9 @@ const decoderLibrary = new DiscriminatedUnionDispatcher<
 	d(shape: EncodedAnyShape): ChunkDecoder {
 		return anyDecoder;
 	},
+	e(shape: EncodedIncrementalChunkShape, cache): ChunkDecoder {
+		return new IncrementalChunkDecoder(cache);
+	},
 });
 
 /**
@@ -228,6 +234,34 @@ export class InlineArrayDecoder implements ChunkDecoder {
 	}
 }
 
+/**
+ * Decoder for {@link EncodedIncrementalChunkShape}s.
+ */
+export class IncrementalChunkDecoder implements ChunkDecoder {
+	public constructor(private readonly cache: DecoderContext<EncodedChunkShape>) {}
+	public decode(_: readonly ChunkDecoder[], stream: StreamCursor): TreeChunk {
+		assert(
+			this.cache.incrementalDecoder !== undefined,
+			0xc27 /* incremental decoder not available for incremental field decoding */,
+		);
+		const chunkReferenceId = readStreamNumber(stream);
+		const batch = this.cache.incrementalDecoder.getEncodedIncrementalChunk(
+			brand(chunkReferenceId),
+		);
+		assert(batch !== undefined, 0xc28 /* Incremental chunk data missing */);
+		// The incremental chunk data is self-describing, i.e., it contain its own shapes list and identifier table.
+		// Use these to create a new decoder context to be used to decode the incremental chunk's data.
+		const context = new DecoderContext(
+			batch.identifiers,
+			batch.shapes,
+			this.cache.idDecodingContext,
+			this.cache.incrementalDecoder,
+		);
+		const chunks = genericDecode(decoderLibrary, context, batch, anyDecoder);
+		return aggregateChunks(chunks);
+	}
+}
+
 /**
  * Decoder for {@link EncodedAnyShape}s.
  */
@@ -300,8 +334,8 @@ export class NodeDecoder implements ChunkDecoder {
 			}
 		}
 
-		for (const field of this.fieldDecoders) {
-			const [key, content] = field(decoders, stream);
+		for (const decoder of this.fieldDecoders) {
+			const [key, content] = decoder(decoders, stream);
 			addField(key, content);
 		}
 

package/src/feature-libraries/chunked-forest/codec/chunkDecodingGeneric.ts

@@ -17,6 +17,7 @@ import {
 } from "./chunkCodecUtilities.js";
 import type { IdDecodingContext } from "./chunkDecoding.js";
 import type { EncodedFieldBatchGeneric, IdentifierOrIndex } from "./formatGeneric.js";
+import type { IncrementalDecoder } from "./codecs.js";
 
 /**
  * General purpose shape based tree decoder which gets its support for specific shapes from the caller.
@@ -50,13 +51,19 @@ export function decode<TEncodedShape extends object, TContext>(
  * Shared data for use in constructing decoders.
  */
 export class DecoderContext<TEncodedShape = unknown> {
-	/**
-	 * @param identifiers - identifier substitution table (use to replace numeric identifier indexes with the actual identifiers from this table).
-	 */
 	public constructor(
+		/**
+		 * Identifier substitution table (use to replace numeric identifier indexes with the actual identifiers from this table).
+		 */
 		public readonly identifiers: readonly string[],
 		public readonly shapes: readonly TEncodedShape[],
 		public readonly idDecodingContext: IdDecodingContext,
+		/**
+		 * To be used to decode incremental chunks, if any.
+		 * @remarks
+		 * See {@link IncrementalDecoder} for more information.
+		 */
+		public readonly incrementalDecoder: IncrementalDecoder | undefined,
 	) {}
 
 	public identifier<T extends string & BrandedType<string, string>>(

package/src/feature-libraries/chunked-forest/codec/codecs.ts

@@ -12,9 +12,24 @@ import {
 	type IJsonCodec,
 	makeVersionedValidatedCodec,
 } from "../../../codec/index.js";
-import { CursorLocationType, type SchemaAndPolicy } from "../../../core/index.js";
-import type { JsonCompatibleReadOnly } from "../../../util/index.js";
-import { TreeCompressionStrategy } from "../../treeCompressionUtils.js";
+import {
+	CursorLocationType,
+	type FieldKey,
+	type ITreeCursorSynchronous,
+	type SchemaAndPolicy,
+	type TreeChunk,
+	type TreeNodeSchemaIdentifier,
+} from "../../../core/index.js";
+import {
+	brandedNumberType,
+	type Brand,
+	type JsonCompatibleReadOnly,
+} from "../../../util/index.js";
+import {
+	TreeCompressionStrategy,
+	TreeCompressionStrategyExtended,
+	type TreeCompressionStrategyPrivate,
+} from "../../treeCompressionUtils.js";
 
 import { decode } from "./chunkDecoding.js";
 import type { FieldBatch } from "./fieldBatch.js";
@@ -22,11 +37,75 @@ import { EncodedFieldBatch, validVersions } from "./format.js";
 import { schemaCompressedEncode } from "./schemaBasedEncode.js";
 import { uncompressedEncode } from "./uncompressedEncode.js";
 
+/**
+ * Reference ID for a chunk that is incrementally encoded.
+ */
+export type ChunkReferenceId = Brand<number, "forest.ChunkReferenceId">;
+const ChunkReferenceId = brandedNumberType<ChunkReferenceId>({ multipleOf: 1, minimum: 0 });
+
+/**
+ * Properties for incremental encoding.
+ * Fields that support incremental encoding will encode their chunks separately by calling `encodeIncrementalField`.
+ * @remarks
+ * This supports features like incremental summarization where the summary from these fields can be re-used if
+ * unchanged between summaries.
+ * Note that each of these chunks that are incrementally encoded is fully self-describing (contain its own shapes
+ * list and identifier table) and does not rely on context from its parent.
+ */
+export interface IncrementalEncoder {
+	/**
+	 * Returns whether a field should be incrementally encoded.
+	 * @param nodeIdentifier - The identifier of the node containing the field.
+	 * @param fieldKey - The key of the field to check.
+	 */
+	shouldEncodeFieldIncrementally(
+		nodeIdentifier: TreeNodeSchemaIdentifier,
+		fieldKey: FieldKey,
+	): boolean;
+	/**
+	 * Called to encode an incremental field at the cursor.
+	 * The chunks for this field are encoded separately from the main buffer.
+	 * @param cursor - The cursor pointing to the field to encode.
+	 * @param chunkEncoder - A function that encodes the contents of the passed chunk in the field.
+	 * @returns The reference IDs of the encoded chunks in the field.
+	 * This is used to retrieve the encoded chunks later.
+	 */
+	encodeIncrementalField(
+		cursor: ITreeCursorSynchronous,
+		chunkEncoder: (chunk: TreeChunk) => EncodedFieldBatch,
+	): ChunkReferenceId[];
+}
+
+/**
+ * Properties for incremental decoding.
+ *
+ * Fields that had their chunks incrementally encoded will retrieve them by calling `getEncodedIncrementalChunk`.
+ * @remarks
+ * See {@link IncrementalEncoder} for more details.
+ */
+export interface IncrementalDecoder {
+	/**
+	 * Called to get the encoded contents of an chunk in an incremental field with the given reference ID.
+	 * @param referenceId - The reference ID of the chunk to retrieve.
+	 * @returns The encoded contents of the chunk.
+	 */
+	getEncodedIncrementalChunk: (referenceId: ChunkReferenceId) => EncodedFieldBatch;
+}
+/**
+ * Combines the properties of {@link IncrementalEncoder} and {@link IncrementalDecoder}.
+ */
+export interface IncrementalEncoderDecoder extends IncrementalEncoder, IncrementalDecoder {}
+
 export interface FieldBatchEncodingContext {
-	readonly encodeType: TreeCompressionStrategy;
+	readonly encodeType: TreeCompressionStrategyPrivate;
 	readonly idCompressor: IIdCompressor;
 	readonly originatorId: SessionId;
 	readonly schema?: SchemaAndPolicy;
+	/**
+	 * An encoder / decoder for encoding and decoding of incremental fields.
+	 * This will be defined if incremental encoding is supported and enabled.
+	 */
+	readonly incrementalEncoderDecoder?: IncrementalEncoderDecoder;
 }
 /**
  * @remarks
@@ -78,6 +157,7 @@ export function makeFieldBatchCodec(
 				case TreeCompressionStrategy.Uncompressed:
 					encoded = uncompressedEncode(data);
 					break;
+				case TreeCompressionStrategyExtended.CompressedIncremental:
 				case TreeCompressionStrategy.Compressed:
 					// eslint-disable-next-line unicorn/prefer-ternary
 					if (context.schema !== undefined) {
@@ -86,6 +166,10 @@ export function makeFieldBatchCodec(
 							context.schema.policy,
 							data,
 							context.idCompressor,
+							// Incremental encoding is only supported for CompressedIncremental.
+							context.encodeType === TreeCompressionStrategyExtended.CompressedIncremental
+								? context.incrementalEncoderDecoder
+								: undefined,
 						);
 					} else {
 						// TODO: consider enabling a somewhat compressed but not schema accelerated encode.
@@ -102,10 +186,14 @@ export function makeFieldBatchCodec(
 		},
 		decode: (data: EncodedFieldBatch, context: FieldBatchEncodingContext): FieldBatch => {
 			// TODO: consider checking data is in schema.
-			return decode(data, {
-				idCompressor: context.idCompressor,
-				originatorId: context.originatorId,
-			}).map((chunk) => chunk.cursor());
+			return decode(
+				data,
+				{
+					idCompressor: context.idCompressor,
+					originatorId: context.originatorId,
+				},
+				context.incrementalEncoderDecoder,
+			).map((chunk) => chunk.cursor());
 		},
 	});
 }

package/src/feature-libraries/chunked-forest/codec/compressedEncode.ts

@@ -11,6 +11,7 @@ import {
 	type FieldKey,
 	type FieldKindIdentifier,
 	type ITreeCursorSynchronous,
+	type TreeChunk,
 	type TreeFieldStoredSchema,
 	type TreeNodeSchemaIdentifier,
 	type Value,
@@ -35,9 +36,10 @@ import {
 	SpecialField,
 	version,
 } from "./format.js";
+import type { ChunkReferenceId, IncrementalEncoder } from "./codecs.js";
 
 /**
- * Encode data from `FieldBatch` into an `EncodedChunk`.
+ * Encode data from `FieldBatch` into an `EncodedFieldBatch`.
  *
  * Optimized for encoded size and encoding performance.
  *
@@ -347,22 +349,48 @@ export class InlineArrayEncoder
 	}
 }
 
+/**
+ * Encodes the shape for a nested array as {@link EncodedNestedArray} shape.
+ */
+export class NestedArrayShape extends ShapeGeneric<EncodedChunkShape> {
+	/**
+	 * @param innerShape - The shape of each item in this nested array.
+	 */
+	public constructor(public readonly innerShape: Shape) {
+		super();
+	}
+
+	public encodeShape(
+		identifiers: DeduplicationTable<string>,
+		shapes: DeduplicationTable<Shape>,
+	): EncodedChunkShape {
+		const shape: EncodedNestedArrayShape =
+			shapes.valueToIndex.get(this.innerShape) ??
+			fail(0xb4f /* index for shape not found in table */);
+		return {
+			a: shape,
+		};
+	}
+
+	public countReferencedShapesAndIdentifiers(
+		identifiers: Counter<string>,
+		shapeDiscovered: (shape: Shape) => void,
+	): void {
+		shapeDiscovered(this.innerShape);
+	}
+}
+
 /**
  * Encodes a field as a nested array with the {@link EncodedNestedArrayShape} shape.
  * @remarks
- * The fact this is also a Shape is an implementation detail of the encoder: that allows the shape it uses to be itself,
+ * The fact this is also exposes a Shape is an implementation detail: it allows the shape it uses to be itself
  * which is an easy way to keep all the related code together without extra objects.
  */
-export class NestedArrayEncoder
-	extends ShapeGeneric<EncodedChunkShape>
-	implements FieldEncoder
-{
-	public readonly shape: Shape;
-
-	public constructor(public readonly inner: NodeEncoder) {
-		super();
-		this.shape = this;
-	}
+export class NestedArrayEncoder implements FieldEncoder {
+	public constructor(
+		public readonly innerEncoder: NodeEncoder,
+		public readonly shape: NestedArrayShape = new NestedArrayShape(innerEncoder.shape),
+	) {}
 
 	public encodeField(
 		cursor: ITreeCursorSynchronous,
@@ -374,7 +402,7 @@ export class NestedArrayEncoder
 		const length = cursor.getFieldLength();
 		forEachNode(cursor, () => {
 			const before = buffer.length;
-			this.inner.encodeNode(cursor, context, buffer);
+			this.innerEncoder.encodeNode(cursor, context, buffer);
 			allNonZeroSize &&= buffer.length - before !== 0;
 		});
 		if (buffer.length === 0) {
@@ -389,27 +417,77 @@ export class NestedArrayEncoder
 			outputBuffer.push(buffer);
 		}
 	}
+}
+
+/**
+ * Encodes a chunk with the {@link EncodedIncrementalChunkShape} shape.
+ * This chunks will be encoded separately, i.e., the contents of the chunk will not be part of the main buffer.
+ * A reference to the chunk will be stored in the main buffer as an {@link ChunkReferenceId}.
+ */
+export class IncrementalChunkShape extends ShapeGeneric<EncodedChunkShape> {
+	/**
+	 * Encodes all the nodes in the chunk at the cursor position using `InlineArrayShape`.
+	 */
+	public static encodeChunk(chunk: TreeChunk, context: EncoderContext): BufferFormat {
+		const chunkOutputBuffer: BufferFormat = [];
+		const nodesEncoder = asNodesEncoder(anyNodeEncoder);
+		const chunkCursor = chunk.cursor();
+		chunkCursor.firstNode();
+		const chunkLength = chunkCursor.chunkLength;
+		for (let index = 0; index < chunkLength; index++) {
+			nodesEncoder.encodeNodes(chunkCursor, context, chunkOutputBuffer);
+		}
+		assert(
+			chunkCursor.mode === CursorLocationType.Fields,
+			0xc29 /* should return to fields mode when finished encoding */,
+		);
+		return chunkOutputBuffer;
+	}
 
 	public encodeShape(
 		identifiers: DeduplicationTable<string>,
 		shapes: DeduplicationTable<Shape>,
 	): EncodedChunkShape {
-		const shape: EncodedNestedArrayShape =
-			shapes.valueToIndex.get(this.inner.shape) ??
-			fail(0xb4f /* index for shape not found in table */);
 		return {
-			a: shape,
+			e: 0 /* EncodedIncrementalChunkShape */,
 		};
 	}
 
 	public countReferencedShapesAndIdentifiers(
 		identifiers: Counter<string>,
 		shapeDiscovered: (shape: Shape) => void,
-	): void {
-		shapeDiscovered(this.inner.shape);
+	): void {}
+
+	public get shape(): this {
+		return this;
 	}
 }
 
+/**
+ * Encodes an incremental field whose chunks are encoded separately and referenced by their {@link ChunkReferenceId}.
+ * The shape of the content of this field is {@link NestedShape} where the items in the array are
+ * the {@link ChunkReferenceId}s of the encoded chunks.
+ */
+export const incrementalFieldEncoder: FieldEncoder = {
+	encodeField(
+		cursor: ITreeCursorSynchronous,
+		context: EncoderContext,
+		outputBuffer: BufferFormat,
+	): void {
+		assert(
+			context.shouldEncodeIncrementally,
+			0xc2a /* incremental encoding must be enabled to use IncrementalFieldShape */,
+		);
+
+		const chunkReferenceIds = context.encodeIncrementalField(cursor, (chunk: TreeChunk) =>
+			IncrementalChunkShape.encodeChunk(chunk, context),
+		);
+		outputBuffer.push(chunkReferenceIds);
+	},
+
+	shape: new NestedArrayShape(new IncrementalChunkShape() /* innerShape */),
+};
+
 /**
  * Encode `value` with `shape` into `outputBuffer`.
  *
@@ -448,6 +526,7 @@ export function encodeValue(
 /**
  * Provides common contextual information during encoding, like schema and policy settings.
  * Also, provides a cache to avoid duplicating equivalent shapes during a batch of encode operations.
+ * @remarks
  * To avoid Shape duplication, any Shapes used in the encoding should either be:
  * - Singletons defined in a static scope.
  * - Cached in this object for future reuse such that all equivalent Shapes are deduplicated.
@@ -461,6 +540,7 @@ export class EncoderContext implements NodeEncodeBuilder, FieldEncodeBuilder {
 		private readonly fieldEncoderFromPolicy: FieldEncoderPolicy,
 		public readonly fieldShapes: ReadonlyMap<FieldKindIdentifier, FlexFieldKind>,
 		public readonly idCompressor: IIdCompressor,
+		private readonly incrementalEncoder: IncrementalEncoder | undefined,
 	) {}
 
 	public nodeEncoderFromSchema(schemaName: TreeNodeSchemaIdentifier): NodeEncoder {
@@ -476,6 +556,30 @@ export class EncoderContext implements NodeEncodeBuilder, FieldEncodeBuilder {
 	public nestedArrayEncoder(inner: NodeEncoder): NestedArrayEncoder {
 		return getOrCreate(this.nestedArrayEncoders, inner, () => new NestedArrayEncoder(inner));
 	}
+
+	public get shouldEncodeIncrementally(): boolean {
+		return this.incrementalEncoder !== undefined;
+	}
+
+	/**
+	 * {@link IncrementalEncoder.encodeIncrementalField}
+	 */
+	public encodeIncrementalField(
+		cursor: ITreeCursorSynchronous,
+		encoder: (chunk: TreeChunk) => BufferFormat,
+	): ChunkReferenceId[] {
+		assert(
+			this.incrementalEncoder !== undefined,
+			0xc2b /* incremental encoding must be enabled */,
+		);
+		// Encoder for the chunk that encodes its data using the provided encoder function and
+		// updates the encoded data for shapes and identifiers.
+		const chunkEncoder = (chunk: TreeChunk): EncodedFieldBatch => {
+			const chunkOutputBuffer = encoder(chunk);
+			return updateShapesAndIdentifiersEncoding(version, [chunkOutputBuffer]);
+		};
+		return this.incrementalEncoder.encodeIncrementalField(cursor, chunkEncoder);
+	}
 }
 
 export interface NodeEncodeBuilder {

package/src/feature-libraries/chunked-forest/codec/format.ts

@@ -47,6 +47,12 @@ export const EncodedInlineArrayShape = Type.Object(
  */
 export const EncodedAnyShape = Type.Literal(0);
 
+/**
+ * Encoded content is a {@link ChunkReferenceId}.
+ * This represents the shape of a chunk that is encoded separately and is referenced by its {@link ChunkReferenceId}.
+ */
+export const EncodedIncrementalChunkShape = Type.Literal(0);
+
 /**
  * Content of the encoded field is specified by the Shape referenced by the ShapeIndex.
  * This is a tuple for conciseness.
@@ -185,6 +191,10 @@ export const EncodedChunkShape = Type.Object(
 		 * {@link EncodedAnyShape} union member.
 		 */
 		d: Type.Optional(EncodedAnyShape),
+		/**
+		 * {@link EncodedIncrementalChunkShape} union member.
+		 */
+		e: Type.Optional(EncodedIncrementalChunkShape),
 	},
 	unionOptions,
 );
@@ -195,6 +205,7 @@ export type EncodedNestedArrayShape = Static<typeof EncodedNestedArrayShape>;
 export type EncodedInlineArrayShape = Static<typeof EncodedInlineArrayShape>;
 export type EncodedNodeShape = Static<typeof EncodedNodeShape>;
 export type EncodedAnyShape = Static<typeof EncodedAnyShape>;
+export type EncodedIncrementalChunkShape = Static<typeof EncodedIncrementalChunkShape>;
 
 export const EncodedFieldBatch = EncodedFieldBatchGeneric(version, EncodedChunkShape);
 export type EncodedFieldBatch = Static<typeof EncodedFieldBatch>;

package/src/feature-libraries/chunked-forest/codec/index.ts

@@ -10,4 +10,8 @@ export {
 	makeFieldBatchCodec,
 	type FieldBatchEncodingContext,
 	fluidVersionToFieldBatchCodecWriteVersion,
+	type IncrementalEncoderDecoder,
+	type IncrementalEncoder,
+	type IncrementalDecoder,
+	type ChunkReferenceId,
 } from "./codecs.js";