@fluidframework/tree 2.73.0 → 2.74.0-368706

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.73.0",
+  "version": "2.74.0-368706",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -101,17 +101,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.73.0",
-    "@fluidframework/container-runtime": "~2.73.0",
-    "@fluidframework/core-interfaces": "~2.73.0",
-    "@fluidframework/core-utils": "~2.73.0",
-    "@fluidframework/datastore-definitions": "~2.73.0",
-    "@fluidframework/driver-definitions": "~2.73.0",
-    "@fluidframework/id-compressor": "~2.73.0",
-    "@fluidframework/runtime-definitions": "~2.73.0",
-    "@fluidframework/runtime-utils": "~2.73.0",
-    "@fluidframework/shared-object-base": "~2.73.0",
-    "@fluidframework/telemetry-utils": "~2.73.0",
+    "@fluid-internal/client-utils": "2.74.0-368706",
+    "@fluidframework/container-runtime": "2.74.0-368706",
+    "@fluidframework/core-interfaces": "2.74.0-368706",
+    "@fluidframework/core-utils": "2.74.0-368706",
+    "@fluidframework/datastore-definitions": "2.74.0-368706",
+    "@fluidframework/driver-definitions": "2.74.0-368706",
+    "@fluidframework/id-compressor": "2.74.0-368706",
+    "@fluidframework/runtime-definitions": "2.74.0-368706",
+    "@fluidframework/runtime-utils": "2.74.0-368706",
+    "@fluidframework/shared-object-base": "2.74.0-368706",
+    "@fluidframework/telemetry-utils": "2.74.0-368706",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@types/ungap__structured-clone": "^1.2.0",
@@ -122,20 +122,20 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.73.0",
-    "@fluid-private/stochastic-test-utils": "~2.73.0",
-    "@fluid-private/test-dds-utils": "~2.73.0",
-    "@fluid-private/test-drivers": "~2.73.0",
+    "@fluid-internal/mocha-test-setup": "2.74.0-368706",
+    "@fluid-private/stochastic-test-utils": "2.74.0-368706",
+    "@fluid-private/test-dds-utils": "2.74.0-368706",
+    "@fluid-private/test-drivers": "2.74.0-368706",
     "@fluid-tools/benchmark": "^0.51.0",
     "@fluid-tools/build-cli": "^0.60.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.60.0",
-    "@fluidframework/container-definitions": "~2.73.0",
-    "@fluidframework/container-loader": "~2.73.0",
-    "@fluidframework/eslint-config-fluid": "~2.73.0",
-    "@fluidframework/test-runtime-utils": "~2.73.0",
-    "@fluidframework/test-utils": "~2.73.0",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.71.0",
+    "@fluidframework/container-definitions": "2.74.0-368706",
+    "@fluidframework/container-loader": "2.74.0-368706",
+    "@fluidframework/eslint-config-fluid": "2.74.0-368706",
+    "@fluidframework/test-runtime-utils": "2.74.0-368706",
+    "@fluidframework/test-utils": "2.74.0-368706",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.73.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",

package/src/codec/codec.ts

@@ -252,9 +252,11 @@ export interface ICodecFamily<TDecoded, TContext = void> {
 /**
  * A version stamp for encoded data.
  *
+ * Strings are used for formats that are not yet officially supported.
+ * When such formats become officially supported/stable, they will be switched to using a number.
  * Undefined is tolerated to enable the scenario where data was not initially versioned.
  */
-export type FormatVersion = number | undefined;
+export type FormatVersion = number | string | undefined;
 
 /**
  * A format version which is dependent on some parent format version.
@@ -525,6 +527,18 @@ export const FluidClientVersion = {
 	 * - FieldBatchFormatVersion v2
 	 */
 	v2_73: "2.73.0",
+
+	/**
+	 * Fluid Framework Client 2.74 and newer.
+	 * @remarks
+	 * New formats introduced in 2.74:
+	 * - SharedTreeSummaryFormatVersion v2
+	 * - DetachedFieldIndexSummaryFormatVersion v2
+	 * - SchemaSummaryFormatVersion v2
+	 * - EditManagerSummaryFormatVersion v2
+	 * - ForestSummaryFormatVersion v2
+	 */
+	v2_74: "2.74.0",
 } as const satisfies Record<string, MinimumVersionForCollab>;
 
 /**

package/src/codec/versioned/codec.ts

@@ -125,7 +125,7 @@ export function makeDiscontinuedCodecVersion<
  */
 export function makeVersionDispatchingCodec<TDecoded, TContext>(
 	family: ICodecFamily<TDecoded, TContext>,
-	options: ICodecOptions & { writeVersion: number },
+	options: ICodecOptions & { writeVersion: number | string },
 ): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
 	const writeCodec = family.resolve(options.writeVersion).json;
 	const supportedVersions = new Set(family.getSupportedFormats());

package/src/codec/versioned/format.ts

@@ -6,6 +6,9 @@
 import { type Static, Type } from "@sinclair/typebox";
 
 export const Versioned = Type.Object({
-	version: Type.Number(),
+	/**
+	 * String versions are used for formats that are not yet officially supported. See {@link FormatVersion} for details.
+	 */
+	version: Type.Union([Type.Number(), Type.String()]),
 });
 export type Versioned = Static<typeof Versioned>;

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,
@@ -83,8 +83,11 @@ export {
 	CursorMarker,
 	isCursor,
 	DetachedFieldIndex,
+	type ReadOnlyDetachedFieldIndex,
+	type DetachedFieldIndexCheckpoint,
 	type ForestRootId,
 	getDetachedFieldContainingPath,
+	getDetachedFieldContainingFieldPath,
 	aboveRootPlaceholder,
 	type DeltaRoot,
 	type DeltaMark,
@@ -102,7 +105,7 @@ export {
 	cursorChunk,
 	tryGetChunk,
 	type ChunkedCursor,
-	type DetachedFieldIndexFormatVersion,
+	DetachedFieldIndexFormatVersion,
 	getCodecTreeForDetachedFieldIndexFormat,
 } from "./tree/index.js";
 
@@ -160,6 +163,7 @@ export {
 	type ChangeEncodingContext,
 	type ChangeFamilyEditor,
 	EditBuilder,
+	type EditorOptions,
 } from "./change-family/index.js";
 
 export {
@@ -208,6 +212,7 @@ export {
 	isAncestor,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
+	newChangeAtomIdTransform,
 	compareRevisions,
 	diffHistories,
 } from "./rebase/index.js";

package/src/core/rebase/changeRebaser.ts

@@ -126,7 +126,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

@@ -29,6 +29,7 @@ export {
 	replaceAtomRevisions,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
+	newChangeAtomIdTransform,
 	compareRevisions,
 } from "./types.js";
 export { RevisionTagCodec } from "./revisionTagCodec.js";

package/src/core/rebase/types.ts

@@ -120,7 +120,10 @@ export function taggedOptAtomId(
 	return taggedAtomId(id, revision);
 }
 
-export function offsetChangeAtomId(id: ChangeAtomId, offset: number): ChangeAtomId {
+export function offsetChangeAtomId<T extends ChangeAtomId = ChangeAtomId>(
+	id: T,
+	offset: number,
+): T {
 	return { ...id, localId: brand(id.localId + offset) };
 }
 
@@ -209,6 +212,10 @@ export function newChangeAtomIdRangeMap<V>(): ChangeAtomIdRangeMap<V> {
 	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds);
 }
 
+export function newChangeAtomIdTransform(): ChangeAtomIdRangeMap<ChangeAtomId> {
+	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetChangeAtomId);
+}
+
 export function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number {
 	const cmp = compareRevisions(a.revision, b.revision);
 	if (cmp !== 0) {

package/src/core/rebase/utils.ts

@@ -327,7 +327,9 @@ export function rebaseBranch<TChange>(
 			},
 		},
 		"sourceChange",
-		() => changeRebaser.compose(editsToCompose),
+		() => {
+			return changeRebaser.compose(editsToCompose);
+		},
 	);
 }
 
@@ -375,23 +377,45 @@ export function rebaseChange<TChange>(
 export function revisionMetadataSourceFromInfo(
 	revInfos: readonly RevisionInfo[],
 ): RevisionMetadataSource {
-	const getIndex = (revision: RevisionTag): number | undefined => {
-		const index = revInfos.findIndex((revInfo) => revInfo.revision === revision);
-		return index >= 0 ? index : undefined;
+	const compareRevisions = (revision1: RevisionTag, revision2: RevisionTag): number => {
+		const index1 = getIndex(revision1);
+		const index2 = getIndex(revision2);
+
+		if (index1 !== undefined) {
+			return index2 !== undefined ? index2 - index1 : -1;
+		}
+
+		return index2 !== undefined ? 1 : 0;
 	};
+
 	const tryGetInfo = (revision: RevisionTag | undefined): RevisionInfo | undefined => {
 		if (revision === undefined) {
 			return undefined;
 		}
-		const index = getIndex(revision);
-		return index === undefined ? undefined : revInfos[index];
+		return revInfos.find((info) => info.revision === revision);
 	};
 
 	const hasRollback = (revision: RevisionTag): boolean => {
 		return revInfos.find((info) => info.rollbackOf === revision) !== undefined;
 	};
 
-	return { getIndex, tryGetInfo, hasRollback };
+	const getIndex = (revision: RevisionTag): number | undefined => {
+		const index = revInfos.findIndex((revInfo) => revInfo.revision === revision);
+		if (index >= 0) {
+			return index;
+		}
+
+		const rollbackIndex = revInfos.findIndex((revInfo) => revInfo.rollbackOf === revision);
+		if (rollbackIndex >= 0) {
+			// This change is the forward revision of a rollback included in revInfos, so it comes after
+			// all revisions in revInfos. Earlier rollbacks have later forward revisions.
+			return 2 * revInfos.length - rollbackIndex;
+		}
+
+		return undefined;
+	};
+
+	return { compareRevisions, tryGetInfo, hasRollback };
 }
 
 export function rebaseChangeOverChanges<TChange>(

package/src/core/tree/detachedFieldIndex.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
@@ -37,10 +37,50 @@ import type {
 } from "./detachedFieldIndexTypes.js";
 import { makeDetachedFieldIndexCodec } from "./detachedFieldIndexCodecs.js";
 
+/**
+ * Readonly interface for {@link DetachedFieldIndex}.
+ */
+export interface ReadOnlyDetachedFieldIndex {
+	/**
+	 * Creates a deep clone of this `DetachedFieldIndex`.
+	 */
+	clone(): DetachedFieldIndex;
+
+	/**
+	 * Returns a field key for the given ID.
+	 * This does not save the field key on the index. To do so, call {@link createEntry}.
+	 */
+	toFieldKey(id: ForestRootId): FieldKey;
+
+	/**
+	 * Returns a node ID for the node in the given field.
+	 * @param field - The field key where the detached node resides.
+	 */
+	fromFieldKey(field: FieldKey): Delta.DetachedNodeId;
+
+	/**
+	 * Returns the `ForestRootId` associated with the given id.
+	 * Returns undefined if no such id is known to the index.
+	 */
+	tryGetEntry(id: Delta.DetachedNodeId): ForestRootId | undefined;
+
+	/**
+	 * Returns the `ForestRootId` associated with the given id.
+	 * Fails if no such id is known to the index.
+	 */
+	getEntry(id: Delta.DetachedNodeId): ForestRootId;
+}
+
+/**
+ * Restores the originating DetachedFieldIndex to the state it was in when the checkpoint was created.
+ * Can be invoked multiple times.
+ */
+export type DetachedFieldIndexCheckpoint = () => void;
+
 /**
  * The tree index records detached field IDs and associates them with a change atom ID.
  */
-export class DetachedFieldIndex {
+export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 	/**
 	 * A mapping from detached node ids to detached fields.
 	 */
@@ -106,6 +146,25 @@ export class DetachedFieldIndex {
 		return clone;
 	}
 
+	/**
+	 * Creates a restorable checkpoint of the current state of the DetachedFieldIndex.
+	 */
+	public createCheckpoint(): DetachedFieldIndexCheckpoint {
+		const clone = this.clone();
+		return () => {
+			this.purge();
+			populateNestedMap(clone.detachedNodeToField, this.detachedNodeToField, true);
+			populateNestedMap(
+				clone.latestRelevantRevisionToFields,
+				this.latestRelevantRevisionToFields,
+				true,
+			);
+			this.rootIdAllocator = idAllocatorFromMaxId(
+				clone.rootIdAllocator.getMaxId(),
+			) as IdAllocator<ForestRootId>;
+		};
+	}
+
 	public *entries(): Generator<{
 		root: ForestRootId;
 		latestRelevantRevision?: RevisionTag;
@@ -201,26 +260,24 @@ export class DetachedFieldIndex {
 		}
 	}
 
-	/**
-	 * Returns a field key for the given ID.
-	 * This does not save the field key on the index. To do so, call {@link createEntry}.
-	 */
 	public toFieldKey(id: ForestRootId): FieldKey {
 		return brand(`${this.name}-${id}`);
 	}
 
-	/**
-	 * Returns the FieldKey associated with the given id.
-	 * Returns undefined if no such id is known to the index.
-	 */
+	public fromFieldKey(field: FieldKey): Delta.DetachedNodeId {
+		// TODO: maintain a lookup table or use field keys that encode the detached node ID
+		for (const { id, root } of this.entries()) {
+			if (this.toFieldKey(root) === field) {
+				return id;
+			}
+		}
+		fail("No known detached roots in the given field");
+	}
+
 	public tryGetEntry(id: Delta.DetachedNodeId): ForestRootId | undefined {
 		return tryGetFromNestedMap(this.detachedNodeToField, id.major, id.minor)?.root;
 	}
 
-	/**
-	 * Returns the FieldKey associated with the given id.
-	 * Fails if no such id is known to the index.
-	 */
 	public getEntry(id: Delta.DetachedNodeId): ForestRootId {
 		const key = this.tryGetEntry(id);
 		assert(key !== undefined, 0x7aa /* Unknown removed node ID */);

package/src/core/tree/index.ts

@@ -59,8 +59,9 @@ export {
 	type NodeIndex,
 	compareUpPaths,
 	compareFieldUpPaths,
-	isDetachedUpPathRoot as isDetachedUpPath,
+	isDetachedUpPathRoot,
 	getDetachedFieldContainingPath,
+	getDetachedFieldContainingFieldPath,
 	type UpPathDefault,
 } from "./pathTree.js";
 export {
@@ -117,9 +118,14 @@ export {
 	type ChunkedCursor,
 } from "./chunk.js";
 
-export { DetachedFieldIndex } from "./detachedFieldIndex.js";
+export {
+	DetachedFieldIndex,
+	type DetachedFieldIndexCheckpoint,
+	type ReadOnlyDetachedFieldIndex,
+} from "./detachedFieldIndex.js";
 
 export { getCodecTreeForDetachedFieldIndexFormat } from "./detachedFieldIndexCodecs.js";
-export { type DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
+export { DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
+export { type FormatV1 } from "./detachedFieldIndexFormatV1.js";
 
 export { type ForestRootId } from "./detachedFieldIndexTypes.js";

package/src/core/tree/pathTree.ts

@@ -126,7 +126,7 @@ export interface FieldUpPath<TUpPath = UpPath> {
  */
 export function isDetachedUpPathRoot<T>(
 	path: UpPath<T> | NormalizedUpPath,
-): path is NormalizedUpPathRoot {
+): path is NormalizedUpPathRoot & { readonly detachedNodeId: DetachedNodeId } {
 	return (path as NormalizedUpPathRoot).detachedNodeId !== undefined;
 }
 
@@ -219,8 +219,8 @@ export function clonePath(path: UpPath | undefined): UpPath | undefined {
  * Gets the elements of the given `path`, ordered from root-most to child-most.
  * @remarks These elements are unchanged and therefore still point "up".
  */
-export function topDownPath(path: UpPath | undefined): UpPath[] {
-	const out: UpPath[] = [];
+export function topDownPath<T extends UpPath<T>>(path: T | undefined): T[] {
+	const out: T[] = [];
 	let curr = path;
 	while (curr !== undefined) {
 		out.push(curr);
@@ -262,7 +262,7 @@ export function compareFieldUpPaths(a: FieldUpPath, b: FieldUpPath): boolean {
 }
 
 /**
- * Checks whether or not a given path is parented under the root field.
+ * Returns the field key for the root field.
  * @param path - the path you want to check.
  * @returns the {@link DetachedField} which contains the path.
  */
@@ -277,3 +277,15 @@ export function getDetachedFieldContainingPath(path: UpPath): DetachedField {
 	}
 	return keyAsDetachedField(path.parentField);
 }
+
+/**
+ * Returns the field key for the root field.
+ * @param path - the path you want to check.
+ * @returns the {@link DetachedField} which contains the path.
+ */
+export function getDetachedFieldContainingFieldPath(path: FieldUpPath): DetachedField {
+	if (path.parent === undefined) {
+		return keyAsDetachedField(path.field);
+	}
+	return getDetachedFieldContainingPath(path.parent);
+}

package/src/feature-libraries/chunked-forest/basicChunk.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob, fail } from "@fluidframework/core-utils/internal";
+import { assert, oob, fail, debugAssert } from "@fluidframework/core-utils/internal";
 
 import {
 	CursorLocationType,
@@ -51,6 +51,12 @@ export class BasicChunk extends ReferenceCountedBase implements TreeChunk {
 		public value?: TreeValue,
 	) {
 		super();
+		debugAssert(() => {
+			for (const field of fields.values()) {
+				if (field.length === 0) return "field must have at least one child";
+			}
+			return true;
+		});
 	}
 
 	public clone(): BasicChunk {

package/src/feature-libraries/chunked-forest/chunkTree.ts

@@ -436,7 +436,12 @@ function newBasicChunkTree(
 ): BasicChunk {
 	return new BasicChunk(
 		cursor.type,
-		new Map(mapCursorFields(cursor, () => [cursor.getFieldKey(), chunkField(cursor, policy)])),
+		new Map(
+			mapCursorFields(cursor, () => {
+				debugAssert(() => cursor.getFieldLength() > 0 || "field must have at least one child");
+				return [cursor.getFieldKey(), chunkField(cursor, policy)];
+			}),
+		),
 		cursor.value,
 	);
 }

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

@@ -29,11 +29,7 @@ import {
 	type Brand,
 	type JsonCompatibleReadOnly,
 } from "../../../util/index.js";
-import {
-	TreeCompressionStrategy,
-	TreeCompressionStrategyExtended,
-	type TreeCompressionStrategyPrivate,
-} from "../../treeCompressionUtils.js";
+import { TreeCompressionStrategy } from "../../treeCompressionUtils.js";
 
 import { decode } from "./chunkDecoding.js";
 import type { FieldBatch } from "./fieldBatch.js";
@@ -109,7 +105,7 @@ export interface IncrementalDecoder {
 export interface IncrementalEncoderDecoder extends IncrementalEncoder, IncrementalDecoder {}
 
 export interface FieldBatchEncodingContext {
-	readonly encodeType: TreeCompressionStrategyPrivate;
+	readonly encodeType: TreeCompressionStrategy;
 	readonly idCompressor: IIdCompressor;
 	readonly originatorId: SessionId;
 	readonly schema?: SchemaAndPolicy;
@@ -190,7 +186,7 @@ export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec
 				case TreeCompressionStrategy.Uncompressed:
 					encoded = uncompressedEncodeFn(data);
 					break;
-				case TreeCompressionStrategyExtended.CompressedIncremental:
+				case TreeCompressionStrategy.CompressedIncremental:
 					assert(
 						writeVersion >= FieldBatchFormatVersion.v2,
 						0xca0 /* Unsupported FieldBatchFormatVersion for incremental encoding; must be v2 or higher */,

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

@@ -3,31 +3,38 @@
  * Licensed under the MIT License.
  */
 
-import type { FieldKey, TreeNodeSchemaIdentifier } from "../../../core/index.js";
-
 /**
- * Policy to determine whether a node / field should be incrementally encoded.
- * @param nodeIdentifier - The identifier of the node containing the field.
- * If undefined, the field is a root field.
- * @param fieldKey - The key of the field to check.
- * @returns whether the node / field should be incrementally encoded.
+ * Policy type to determine whether one of more fields of a {@link NodeKind | node} in a schema should be incrementally encoded.
+ * @param nodeIdentifier - The identifier of the node. The node is one of the kinds defined in {@link NodeKind}.
+ * @param fieldKey - An optional key for fields in the node. It must be one of the following based on the kind of node.
+ * Policy implementations may throw an error if the provided key is invalid for the node kind:
+ * - {@link NodeKind.Object | object} - Must be defined and should be the key of one of its fields. If the object node does not
+ * have a field with the specified key, returns false.
+ * - {@link NodeKind.Array | array} - Must be defined and be the "" (empty string) which is special value for arrays.
+ * - {@link NodeKind.Map | map} and {@link NodeKind.Record | record} - Must be undefined.
+ * - {@link NodeKind.Leaf | leaf} - Must be undefined. Leaf nodes do not support incremental encoding. If called for leaf nodes,
+ * returns false.
+ *
  * @remarks
+ * See {@link incrementalEncodingPolicyForAllowedTypes} for a reference policy implementation.
+ *
  * Incremental encoding has a significant size overhead,
  * but allows reuse of previously encoded unchanged subtrees.
  * Thus it should only be enabled for large subtrees which are modified infrequently.
  * TODO: AB#9068: Measure the actual overhead.
+ * @alpha
  */
 export type IncrementalEncodingPolicy = (
-	nodeIdentifier: TreeNodeSchemaIdentifier | undefined,
-	fieldKey: FieldKey,
+	nodeIdentifier: string | undefined,
+	fieldKey?: string,
 ) => boolean;
 
 /**
  * Default policy for incremental encoding is to not encode incrementally.
  */
 export const defaultIncrementalEncodingPolicy: IncrementalEncodingPolicy = (
-	nodeIdentifier: TreeNodeSchemaIdentifier | undefined,
-	fieldKey: FieldKey,
+	nodeIdentifier: string | undefined,
+	fieldKey?: string,
 ): boolean => {
 	return false;
 };

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

@@ -180,16 +180,16 @@ export function getNodeEncoder(
 	schemaName: TreeNodeSchemaIdentifier,
 	incrementalEncoder?: IncrementalEncoder,
 ): NodeShapeBasedEncoder {
+	const shouldEncodeIncrementally =
+		incrementalEncoder?.shouldEncodeIncrementally ?? defaultIncrementalEncodingPolicy;
 	const schema =
 		storedSchema.nodeSchema.get(schemaName) ?? fail(0xb53 /* missing node schema */);
 
+	// This handles both object and array nodes.
 	if (schema instanceof ObjectNodeStoredSchema) {
 		// TODO:Performance:
 		// consider moving some optional and sequence fields to extra fields if they are commonly empty
 		// to reduce encoded size.
-
-		const shouldEncodeIncrementally =
-			incrementalEncoder?.shouldEncodeIncrementally ?? defaultIncrementalEncodingPolicy;
 		const objectNodeFields: KeyedFieldEncoder[] = [];
 		for (const [key, field] of schema.objectNodeFields ?? []) {
 			const fieldEncoder = shouldEncodeIncrementally(schemaName, key)
@@ -213,13 +213,13 @@ export function getNodeEncoder(
 		);
 		return shape;
 	}
+
+	// This handles both maps and record nodes.
 	if (schema instanceof MapNodeStoredSchema) {
-		const shape = new NodeShapeBasedEncoder(
-			schemaName,
-			false,
-			[],
-			fieldBuilder.fieldEncoderFromSchema(schema.mapFields),
-		);
+		const fieldEncoder = shouldEncodeIncrementally(schemaName)
+			? incrementalFieldEncoder
+			: fieldBuilder.fieldEncoderFromSchema(schema.mapFields);
+		const shape = new NodeShapeBasedEncoder(schemaName, false, [], fieldEncoder);
 		return shape;
 	}
 	fail(0xb54 /* unsupported node kind */);