@fluidframework/tree 2.93.0 → 2.100.0

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,
@@ -166,10 +166,19 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		if (this.nestedCursor !== undefined) {
 			return this.nestedCursor.mode;
 		}
-		// Compute the number of nodes deep the current depth is.
-		// We want the floor of the result, which can computed using a bitwise shift assuming the depth is less than 2^31, which seems safe.
-		// eslint-disable-next-line no-bitwise
-		const halfHeight = (this.siblingStack.length + 1) >> 1;
+		this.assertChunkStacksMatchNodeDepth();
+		return this.siblingStack.length % 2 === 0
+			? CursorLocationType.Fields
+			: CursorLocationType.Nodes;
+	}
+
+	/**
+	 * Asserts that the node-only stacks (`indexOfChunkStack` and `indexWithinChunkStack`) are in sync with `siblingStack`.
+	 * Since `siblingStack` interleaves field and node levels while the node-only stacks are pushed/popped only on node-level transitions,
+	 * their length should always equal the number of node levels traversed.
+	 */
+	private assertChunkStacksMatchNodeDepth(): void {
+		const halfHeight = this.getNodeOnlyHeightFromHeight();
 		assert(
 			this.indexOfChunkStack.length === halfHeight,
 			0x51c /* unexpected indexOfChunkStack */,
@@ -178,9 +187,6 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 			this.indexWithinChunkStack.length === halfHeight,
 			0x51d /* unexpected indexWithinChunkStack */,
 		);
-		return this.siblingStack.length % 2 === 0
-			? CursorLocationType.Fields
-			: CursorLocationType.Nodes;
 	}
 
 	public getFieldKey(): FieldKey {
@@ -203,9 +209,32 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		return this.indexStack[height] ?? oob();
 	}
 
-	private getStackedNode(height: number): BasicChunk {
-		const index = this.getStackedNodeIndex(height);
-		return (this.siblingStack[height] as readonly TreeChunk[])[index] as BasicChunk;
+	private getStackedChunkIndex(height: number): number {
+		assert(height % 2 === 1, 0xcf3 /* must be node height */);
+		assert(height >= 0, 0xcf4 /* must not be above root */);
+		return this.indexOfChunkStack[this.getNodeOnlyHeightFromHeight(height)] ?? oob();
+	}
+
+	private getStackedChunk(height: number): BasicChunk {
+		const index = this.getStackedChunkIndex(height);
+		const chunk = (this.siblingStack[height] as readonly TreeChunk[])[index];
+		debugAssert(() => chunk instanceof BasicChunk || "only basic chunks are expected");
+		return chunk as BasicChunk;
+	}
+
+	/**
+	 * Converts a {@link height}, which contains field and node levels, into the corresponding depth/index
+	 * for the node-only stacks ({@link indexOfChunkStack} and {@link indexWithinChunkStack}), which are
+	 * only pushed on node-level transitions.
+	 *
+	 * @param height - A depth in {@link siblingStack} to convert. Defaults to {@link siblingStack}'s
+	 * current length, which gives the current depth of the node-only stacks.
+	 * @returns `floor(height / 2)` — the number of node levels at or below the given stack height.
+	 */
+	private getNodeOnlyHeightFromHeight(height: number = this.siblingStack.length): number {
+		// The bitwise shift computes the floor, which is valid assuming the depth is less than 2^31, which seems safe.
+		// eslint-disable-next-line no-bitwise
+		return height >> 1;
 	}
 
 	public getFieldLength(): number {
@@ -322,6 +351,11 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		assert(this.mode === CursorLocationType.Nodes, 0x528 /* must be in nodes mode */);
 		this.siblingStack.push(this.siblings);
 		this.indexStack.push(this.index);
+		// Save the chunk array position of the current node. When siblings contain
+		// multi node chunks, the flat node index diverges from the array position,
+		// so getField needs this to locate the parent in the sibling array.
+		this.indexOfChunkStack.push(this.indexOfChunk);
+		this.indexWithinChunkStack.push(this.indexWithinChunk);
 
 		// For fields, siblings are only used for key lookup and
 		// nextField and which has arbitrary iteration order,
@@ -330,6 +364,7 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		// at the cost of an allocation here.
 		this.index = 0;
 		this.siblings = [key];
+		this.assertChunkStacksMatchNodeDepth();
 	}
 
 	public nextField(): boolean {
@@ -355,8 +390,11 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 
 		this.siblingStack.push(this.siblings);
 		this.indexStack.push(this.index);
+		this.indexOfChunkStack.push(this.indexOfChunk);
+		this.indexWithinChunkStack.push(this.indexWithinChunk);
 		this.index = 0;
 		this.siblings = [...fields.keys()]; // TODO: avoid this copy
+		this.assertChunkStacksMatchNodeDepth();
 		return true;
 	}
 
@@ -422,12 +460,11 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		}
 		this.siblingStack.push(this.siblings);
 		this.indexStack.push(this.index);
-		this.indexOfChunkStack.push(this.indexOfChunk);
-		this.indexWithinChunkStack.push(this.indexWithinChunk);
 		this.index = 0;
 		this.siblings = siblings;
 		this.indexOfChunk = 0;
 		this.indexWithinChunk = 0;
+		this.assertChunkStacksMatchNodeDepth();
 		this.initNestedCursor();
 		return true;
 	}
@@ -486,6 +523,12 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		this.siblings =
 			this.siblingStack.pop() ?? fail(0xaf0 /* Unexpected siblingStack.length */);
 		this.index = this.indexStack.pop() ?? fail(0xaf1 /* Unexpected indexStack.length */);
+		this.indexOfChunk =
+			this.indexOfChunkStack.pop() ?? fail(0xcf5 /* Unexpected indexOfChunkStack.length */);
+		this.indexWithinChunk =
+			this.indexWithinChunkStack.pop() ??
+			fail(0xcf6 /* Unexpected indexWithinChunkStack.length */);
+		this.assertChunkStacksMatchNodeDepth();
 	}
 
 	public exitNode(): void {
@@ -502,18 +545,27 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		this.siblings =
 			this.siblingStack.pop() ?? fail(0xaf2 /* Unexpected siblingStack.length */);
 		this.index = this.indexStack.pop() ?? fail(0xaf3 /* Unexpected indexStack.length */);
-		this.indexOfChunk =
-			this.indexOfChunkStack.pop() ?? fail(0xaf4 /* Unexpected indexOfChunkStack.length */);
-		this.indexWithinChunk =
-			this.indexWithinChunkStack.pop() ??
-			fail(0xaf5 /* Unexpected indexWithinChunkStack.length */);
+		// At the Fields level these aren't semantically used, but reset for consistent state
+		// (so a fully-iterated cursor matches a fresh cursor at the same logical position).
+		this.indexOfChunk = 0;
+		this.indexWithinChunk = 0;
+		this.assertChunkStacksMatchNodeDepth();
 	}
 
 	private getNode(): BasicChunk {
 		assert(this.mode === CursorLocationType.Nodes, 0x52f /* can only get node when in node */);
-		return (this.siblings as TreeChunk[])[this.index] as BasicChunk;
+		const chunk = (this.siblings as TreeChunk[])[this.indexOfChunk];
+		debugAssert(() => chunk instanceof BasicChunk || "only basic chunks are expected");
+		return chunk as BasicChunk;
 	}
 
+	/**
+	 * Resolves the chunks that make up the field the cursor is currently in. At the root, this is
+	 * {@link root} directly. Otherwise, the cursor must be in {@link CursorLocationType.Fields} mode,
+	 * and the result is looked up on the parent node using the current field key.
+	 *
+	 * @returns The chunks that make up the field the cursor is currently in.
+	 */
 	private getField(): readonly TreeChunk[] {
 		if (this.siblingStack.length === 0) {
 			return this.root;
@@ -522,7 +574,11 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 			this.mode === CursorLocationType.Fields,
 			0x530 /* can only get field when in fields */,
 		);
-		const parent = this.getStackedNode(this.indexStack.length - 1);
+		// The parent node is the `BasicChunk` in the node array at the top of
+		// `siblingStack` while we are in `CursorLocationType.Fields` mode. We need the parent
+		// since a field's chunks are stored on the parent node's `BasicChunk.fields` map, not on
+		// the cursor itself.
+		const parent = this.getStackedChunk(this.siblingStack.length - 1);
 		const key: FieldKey = this.getFieldKey();
 		const field = parent.fields.get(key) ?? [];
 		return field;

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

@@ -49,8 +49,8 @@ import {
 	type EncodedNestedArrayShape,
 	type EncodedNodeShape,
 	type EncodedValueShape,
-	FieldBatchFormatVersion,
 	SpecialField,
+	supportsIncrementalEncoding,
 } from "./format/index.js";
 
 export interface IdDecodingContext {
@@ -256,7 +256,7 @@ export class IncrementalChunkDecoder implements ChunkDecoder {
 
 		const chunkDecoder = (batch: EncodedFieldBatchV2): TreeChunk => {
 			assert(
-				batch.version >= FieldBatchFormatVersion.v2,
+				supportsIncrementalEncoding(batch.version),
 				0xc9f /* Unsupported FieldBatchFormatVersion for incremental chunks; must be v2 or higher */,
 			);
 			const context = new DecoderContext(

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

@@ -30,6 +30,7 @@ import {
 	EncodedFieldBatchV1,
 	EncodedFieldBatchV2,
 	FieldBatchFormatVersion,
+	supportsIncrementalEncoding,
 	type EncodedFieldBatchV1OrV2,
 } from "./format/index.js";
 import type { IncrementalEncodingPolicy } from "./incrementalEncodingPolicy.js";
@@ -147,7 +148,7 @@ function makeFieldBatchCodecForVersion(
 				}
 				case TreeCompressionStrategy.CompressedIncremental: {
 					assert(
-						version >= FieldBatchFormatVersion.v2,
+						supportsIncrementalEncoding(version),
 						0xca0 /* Unsupported FieldBatchFormatVersion for incremental encoding; must be v2 or higher */,
 					);
 					// Incremental encoding is only supported for CompressedIncremental.

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

@@ -36,8 +36,9 @@ import {
 	type EncodedFieldBatchV1OrV2,
 	type EncodedNestedArrayShape,
 	type EncodedValueShape,
-	FieldBatchFormatVersion,
+	type FieldBatchFormatVersion,
 	SpecialField,
+	supportsIncrementalEncoding,
 } from "./format/index.js";
 
 /**
@@ -461,7 +462,7 @@ export const incrementalFieldEncoder: FieldEncoder = {
 			0xc88 /* incremental encoder must be defined to use incrementalFieldEncoder */,
 		);
 		assert(
-			context.version >= FieldBatchFormatVersion.v2,
+			supportsIncrementalEncoding(context.version),
 			0xca1 /* Unsupported FieldBatchFormatVersion for incremental encoding; must be v2 or higher */,
 		);
 

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

@@ -28,7 +28,6 @@ export const Count = Type.Number({ multipleOf: 1, minimum: 0 });
 
 const EncodedFieldBatchBase = Type.Object(
 	{
-		version: Type.Number(),
 		identifiers: Type.Array(Type.String()),
 		/**
 		 * Top level array is list of field from batch.

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

@@ -20,6 +20,7 @@ export {
 	FieldBatchFormatVersion,
 	EncodedFieldBatchV1,
 	EncodedFieldBatchV2,
+	supportsIncrementalEncoding,
 	type EncodedFieldBatchV1OrV2,
 	type EncodedFieldBatchV1AndV2,
 	type EncodedChunkShapeV1OrV2,

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

@@ -31,6 +31,21 @@ export const FieldBatchFormatVersion = strictEnum("FieldBatchFormatVersion", {
 	v2: 2,
 });
 
+/**
+ * Whether the given format version supports incremental chunk encoding.
+ *
+ * @remarks
+ * This helper should be used for comparison since experimental versions
+ * can be a string.
+ */
+export function supportsIncrementalEncoding(version: FieldBatchFormatVersion): boolean {
+	if (version === FieldBatchFormatVersion.v1) {
+		return false;
+	}
+
+	return true;
+}
+
 /**
  * Encoded {@link FieldBatch} using V1 format.
  * @remarks

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

@@ -20,7 +20,7 @@ import {
 	cursorChunk,
 	dummyRoot,
 } from "../../core/index.js";
-import { ReferenceCountedBase, hasSome } from "../../util/index.js";
+import { ReferenceCountedBase, getOrCreate, hasSome } from "../../util/index.js";
 import { SynchronousCursor, prefixFieldPath, prefixPath } from "../treeCursorUtils.js";
 
 /**
@@ -83,6 +83,23 @@ export class UniformChunk extends ReferenceCountedBase implements TreeChunk {
  */
 export type FieldShape = readonly [FieldKey, TreeShape, number];
 
+/**
+ * Maximum topLevelLength value (exclusive) for which {@link TreeShape.withTopLevelLength}
+ * caches the resulting {@link ChunkShape}. Values at or above this threshold always
+ * create a new instance to prevent unbounded cache growth.
+ *
+ * @remarks
+ * This value is an estimation of the general size needed to cover current workflows,
+ * not a researched constant, and is safe to tune as workloads change.
+ *
+ * Raising this value captures more chunk sizes in the cache, at the cost of
+ * each `TreeShape` retaining up to `chunkShapeCacheLimit - 1` cached entries for the
+ * lifetime of the shape. Lowering it reduces memory held per `TreeShape` but forces
+ * small chunks, where the relative cost of rebuilding `positions` is highest, to pay
+ * the construction cost on every call.
+ */
+const chunkShapeCacheLimit = 8;
+
 /**
  * The "shape" of a tree.
  * Does not contain the actual values from  the tree, but describes everything else,
@@ -110,7 +127,13 @@ export class TreeShape {
 	public readonly mayContainCompressedIds: boolean;
 
 	/**
-	 *
+	 * Cache for ChunkShape instances created by {@link withTopLevelLength}.
+	 * `topLevelLength` is always a positive integer (enforced by the {@link ChunkShape} constructor),
+	 * so the cache only ever holds entries for values in `1..chunkShapeCacheLimit - 1` to prevent unbounded growth.
+	 */
+	private readonly chunkShapeCache: Map<number, ChunkShape> = new Map();
+
+	/**
 	 * @param type - {@link TreeNodeSchemaIdentifier} used to compare shapes.
 	 * @param hasValue - whether or not the TreeShape has a value.
 	 * @param fieldsArray - an array of {@link FieldShape} values, which contains a TreeShape for each FieldKey.
@@ -179,6 +202,13 @@ export class TreeShape {
 	}
 
 	public withTopLevelLength(topLevelLength: number): ChunkShape {
+		if (topLevelLength < chunkShapeCacheLimit) {
+			return getOrCreate(
+				this.chunkShapeCache,
+				topLevelLength,
+				() => new ChunkShape(this, topLevelLength),
+			);
+		}
 		return new ChunkShape(this, topLevelLength);
 	}
 }

package/src/feature-libraries/forest-summary/incrementalSummaryBuilder.ts

@@ -50,10 +50,12 @@ interface ChunkLoadProperties {
 	 */
 	readonly encodedContents: EncodedFieldBatchV2;
 	/**
-	 * The path for this chunk's contents in the summary tree relative to the forest's summary tree.
-	 * This path is used to generate a summary handle for the chunk if it doesn't change between summaries.
+	 * The reference ID of this chunk's parent in the summary tree, or `undefined` if this chunk is
+	 * at the top level (directly under the forest summary tree).
+	 * Stored here so that {@link ForestIncrementalSummaryBuilder.decodeIncrementalChunk} can
+	 * reconstruct the correct {@link ChunkSummaryProperties} without re-parsing a path string.
 	 */
-	readonly summaryPath: string;
+	readonly parentReferenceId: ChunkReferenceId | undefined;
 }
 
 /**
@@ -68,10 +70,20 @@ interface ChunkSummaryProperties {
 	 */
 	readonly referenceId: ChunkReferenceId;
 	/**
-	 * The path for this chunk's summary in the summary tree relative to the forest's summary tree.
-	 * This path is used to generate a summary handle for the chunk if it doesn't change between summaries.
+	 * The reference ID of this chunk's parent in the summary tree, or `undefined` if this chunk
+	 * is at the top level (has no incremental parent).
+	 *
+	 * @remarks
+	 * Storing only the immediate parent (rather than the full path string) keeps every chunk's
+	 * tracking entry correct even when an ancestor is re-encoded and receives a new reference ID.
+	 * The full summary path is computed on demand by {@link ForestIncrementalSummaryBuilder.computeHandlePathInLatestSummary}
+	 * by walking up the parent chain through {@link TrackedSummaryProperties.latestSummaryRefIdMap}.
+	 *
+	 * If a parent chunk is encoded as a handle in the current summary its reference ID is unchanged,
+	 * so its children's `parentReferenceId` values copied forward by `completeSummary` remain valid
+	 * without any additional update.
 	 */
-	readonly summaryPath: string;
+	readonly parentReferenceId: ChunkReferenceId | undefined;
 }
 
 /**
@@ -109,6 +121,13 @@ interface TrackedSummaryProperties {
 	 * Serializes content (including {@link (IFluidHandle:interface)}s) for adding to a summary blob.
 	 */
 	stringify: SummaryElementStringifier;
+	/**
+	 * Reverse lookup map for the latest summary: maps each chunk's {@link ChunkReferenceId} to its
+	 * {@link ChunkSummaryProperties}.
+	 * Used by {@link ForestIncrementalSummaryBuilder.computeHandlePathInLatestSummary} to traverse
+	 * the parent chain when generating handle paths.
+	 */
+	readonly latestSummaryRefIdMap: Map<ChunkReferenceId, ChunkSummaryProperties>;
 }
 
 /**
@@ -177,6 +196,16 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 	/**
 	 * For a given summary sequence number, keeps track of a chunk's properties that will be used to generate
 	 * a summary handle for the chunk if it does not change between summaries.
+	 *
+	 * @remarks
+	 * `chunk` (the TreeChunk object) is used as the map key by object identity.
+	 * This assumes each chunk appears at exactly one position in the forest — an invariant that holds because every
+	 * node in a tree has a single parent.
+	 * If the forest ever introduced structural sharing (two positions backed by the same TreeChunk object),
+	 * a second call here would silently overwrite the first entry, causing the first position's handle to point
+	 * to the second position's parent in subsequent summaries. In theory, this should be fine from summary perspective
+	 * because the chunk contents are the same. But, it could lead to confusing handle paths in the summary tree and
+	 * may lead to other unexpected behavior. Adequate tests should be added if structural sharing is introduced.
 	 */
 	private readonly chunkTrackingPropertiesMap: NestedMap<
 		number,
@@ -249,12 +278,14 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		// the contents of incremental chunks in any sub-trees.
 		const downloadChunkContentsInTree = async (
 			snapshotTree: ISnapshotTree,
-			parentTreeKey: string,
+			parentPathSegments: string[],
+			parentReferenceId: ChunkReferenceId | undefined,
 		): Promise<void> => {
 			// All trees in the snapshot tree are for incremental chunks. The key is the chunk's reference ID
 			// and the value is the snapshot tree for the chunk.
 			for (const [chunkReferenceId, chunkSnapshotTree] of Object.entries(snapshotTree.trees)) {
-				const chunkSubTreePath = `${parentTreeKey}${chunkReferenceId}`;
+				const chunkSubTreeSegments = [...parentPathSegments, chunkReferenceId];
+				const chunkSubTreePath = chunkSubTreeSegments.join("/");
 				const chunkContentsPath = `${chunkSubTreePath}/${summaryContentBlobKey}`;
 				if (!(await args.services.contains(chunkContentsPath))) {
 					throw new LoggingError(
@@ -266,7 +297,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				)) as EncodedFieldBatchV2; // TODO: this should use a codec to validate the data instead of just type casting.
 				this.loadedChunksMap.set(chunkReferenceId, {
 					encodedContents: chunkContents,
-					summaryPath: chunkSubTreePath,
+					parentReferenceId,
 				});
 
 				const chunkReferenceIdNumber = Number(chunkReferenceId);
@@ -275,10 +306,15 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				);
 
 				// Recursively download the contents of chunks in this chunk's sub tree.
-				await downloadChunkContentsInTree(chunkSnapshotTree, `${chunkSubTreePath}/`);
+				await downloadChunkContentsInTree(
+					chunkSnapshotTree,
+					chunkSubTreeSegments,
+					brand(chunkReferenceIdNumber),
+				);
 			}
 		};
-		await downloadChunkContentsInTree(forestTree, "");
+		// parentReferenceId is undefined for the root of the forest tree.
+		await downloadChunkContentsInTree(forestTree, [], undefined /* parentReferenceId */);
 	}
 
 	/**
@@ -319,6 +355,19 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		}
 
 		this.latestSummarySequenceNumber = incrementalSummaryContext.latestSummarySequenceNumber;
+
+		// Build a reverse lookup map (referenceId → properties) for the latest summary so that
+		// computeHandlePathInLatestSummary can traverse the parent chain without iterating the whole map.
+		const latestSummaryRefIdMap: Map<ChunkReferenceId, ChunkSummaryProperties> = new Map();
+		const latestTracking = this.chunkTrackingPropertiesMap.get(
+			this.latestSummarySequenceNumber,
+		);
+		if (latestTracking !== undefined) {
+			for (const properties of latestTracking.values()) {
+				latestSummaryRefIdMap.set(properties.referenceId, properties);
+			}
+		}
+
 		this.trackedSummaryProperties = {
 			summarySequenceNumber: incrementalSummaryContext.summarySequenceNumber,
 			latestSummaryBasePath: incrementalSummaryContext.summaryPath,
@@ -326,10 +375,39 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			parentSummaryBuilder: builder,
 			fullTree,
 			stringify,
+			latestSummaryRefIdMap,
 		};
 		return ForestIncrementalSummaryBehavior.Incremental;
 	}
 
+	/**
+	 * Computes a chunk's path in the latest summary by traversing up the parent chain via
+	 * {@link latestSummaryRefIdMap}.
+	 *
+	 * Each {@link ChunkSummaryProperties.parentReferenceId} points to the chunk's parent as it
+	 * appeared in the summary where the entry was last written. Walking up the chain from the
+	 * chunk to the root produces the full path that can be used in a summary handle path.
+	 */
+	private computeHandlePathInLatestSummary(chunkProperties: ChunkSummaryProperties): string {
+		const { latestSummaryRefIdMap } = this.requireTrackingSummary();
+		const pathSegments: string[] = [];
+		let current: ChunkSummaryProperties | undefined = chunkProperties;
+		while (current !== undefined) {
+			pathSegments.push(`${current.referenceId}`);
+			if (current.parentReferenceId === undefined) {
+				break;
+			}
+			current = latestSummaryRefIdMap.get(current.parentReferenceId);
+			assert(
+				current !== undefined,
+				0xcf7 /* Parent chunk not found in latest summary tracking */,
+			);
+		}
+		// Segments are collected leaf-to-root and then reversed. The alternative would be to use unshift
+		// instead of push and reverse. However, using push and reverse is O(n) whereas using unshift would be O(n²).
+		return pathSegments.reverse().join("/");
+	}
+
 	/**
 	 * {@link IncrementalEncoder.encodeIncrementalField}
 	 * @remarks Returns an empty array if the field has no content.
@@ -344,8 +422,6 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		const chunkReferenceIds: ChunkReferenceId[] = [];
 		const chunks = this.getChunkAtCursor(cursor);
 		for (const chunk of chunks) {
-			let chunkProperties: ChunkSummaryProperties;
-
 			// Try and get the properties of the chunk from the latest successful summary.
 			// If it exists and the summary is not a full tree, use the properties to generate a summary handle.
 			// If it does not exist, encode the chunk and generate new properties for it.
@@ -354,28 +430,29 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				this.latestSummarySequenceNumber,
 				chunk,
 			);
+			let chunkReferenceId: ChunkReferenceId;
 			if (previousChunkProperties !== undefined && !trackedSummaryProperties.fullTree) {
-				chunkProperties = previousChunkProperties;
+				chunkReferenceId = previousChunkProperties.referenceId;
+				// Compute this chunk's path in the latest summary by traversing the parent chain.
+				// Using parentReferenceId traversal (rather than a stored path string) ensures the
+				// path is correct even when an ancestor was re-encoded in a prior summary and
+				// received a new referenceId — the stored summaryPath would have been stale in
+				// that case.
+				const handlePath = this.computeHandlePathInLatestSummary(previousChunkProperties);
 				trackedSummaryProperties.parentSummaryBuilder.addHandle(
-					`${chunkProperties.referenceId}`,
+					`${chunkReferenceId}`,
 					SummaryType.Tree,
-					`${trackedSummaryProperties.latestSummaryBasePath}/${chunkProperties.summaryPath}`,
+					`${trackedSummaryProperties.latestSummaryBasePath}/${handlePath}`,
 				);
 			} else {
 				// Generate a new reference ID for the chunk.
 				const newReferenceId: ChunkReferenceId = brand(this.nextReferenceId++);
+				chunkReferenceId = newReferenceId;
 
-				// Add the reference ID of this chunk to the chunk summary path and use the path as the summary path
-				// for the chunk in its summary properties.
-				// This is done before encoding the chunk so that the summary path is updated correctly when encoding
-				// any incremental chunks that are under this chunk.
+				// Add the reference ID of this chunk to the chunk summary path before encoding so
+				// that any incremental chunks in the subtree use the correct parent path.
 				trackedSummaryProperties.chunkSummaryPath.push(newReferenceId);
 
-				chunkProperties = {
-					referenceId: newReferenceId,
-					summaryPath: trackedSummaryProperties.chunkSummaryPath.join("/"),
-				};
-
 				const parentSummaryBuilder = trackedSummaryProperties.parentSummaryBuilder;
 				// Create a new summary builder for this chunk to build its summary tree which will be stored in the
 				// parent's summary tree under its reference ID.
@@ -400,13 +477,21 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				trackedSummaryProperties.chunkSummaryPath.pop();
 			}
 
+			// Get the parent reference ID from the current chunk summary path.
+			// For the root of the forest tree, the parent reference ID is undefined.
+			// For all other chunks, the parent reference ID is the last element in the current chunk summary path.
+			const chunkSummaryPathLength = trackedSummaryProperties.chunkSummaryPath.length;
+			const parentReferenceId: ChunkReferenceId | undefined =
+				chunkSummaryPathLength > 0
+					? trackedSummaryProperties.chunkSummaryPath[chunkSummaryPathLength - 1]
+					: undefined;
 			setInNestedMap(
 				this.chunkTrackingPropertiesMap,
 				trackedSummaryProperties.summarySequenceNumber,
 				chunk,
-				chunkProperties,
+				{ referenceId: chunkReferenceId, parentReferenceId },
 			);
-			chunkReferenceIds.push(chunkProperties.referenceId);
+			chunkReferenceIds.push(chunkReferenceId);
 		}
 		return chunkReferenceIds;
 	}
@@ -480,9 +565,9 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		referenceId: ChunkReferenceId,
 		chunkDecoder: (encoded: EncodedFieldBatchV2) => TreeChunk,
 	): TreeChunk {
-		const ChunkLoadProperties = this.loadedChunksMap.get(`${referenceId}`);
-		assert(ChunkLoadProperties !== undefined, 0xc86 /* Encoded incremental chunk not found */);
-		const chunk = chunkDecoder(ChunkLoadProperties.encodedContents);
+		const chunkLoadProperties = this.loadedChunksMap.get(`${referenceId}`);
+		assert(chunkLoadProperties !== undefined, 0xc86 /* Encoded incremental chunk not found */);
+		const chunk = chunkDecoder(chunkLoadProperties.encodedContents);
 
 		// Account for the reference about to be added in `chunkTrackingPropertiesMap`
 		// to ensure that no other users of this chunk think they have unique ownership.
@@ -493,7 +578,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		// when a new client starts to summarize.
 		setInNestedMap(this.chunkTrackingPropertiesMap, this.initialSequenceNumber, chunk, {
 			referenceId,
-			summaryPath: ChunkLoadProperties.summaryPath,
+			parentReferenceId: chunkLoadProperties.parentReferenceId,
 		});
 		return chunk;
 	}

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.93.0";
+export const pkgVersion = "2.100.0";