@fluidframework/tree 2.73.0 → 2.74.0-368706

package/src/feature-libraries/flex-tree/lazyField.ts

@@ -9,7 +9,6 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import {
 	type AnchorNode,
 	CursorLocationType,
-	type ExclusiveMapTree,
 	type FieldAnchor,
 	type FieldKey,
 	type FieldKindIdentifier,
@@ -26,18 +25,21 @@ import { disposeSymbol, getOrCreate } from "../../util/index.js";
 import {
 	FieldKinds,
 	MappedEditBuilder,
-	type IDefaultEditBuilder,
-	type OptionalFieldEditBuilder,
-	type SequenceFieldEditBuilder,
-	type ValueFieldEditBuilder,
+	type SequenceFieldEditor,
+	type RequiredFieldEditor,
+	type DataEditor,
+	type OptionalFieldEditor,
+	type DetachedRootLocation,
+	type DetachedRootsLocation,
 } from "../default-schema/index.js";
-import { cursorForMapTreeField } from "../mapTreeCursor.js";
+import { cursorForMapTreeField, type MinimalMapTreeNodeView } from "../mapTreeCursor.js";
 import type { FlexFieldKind } from "../modular-schema/index.js";
 
 import type { Context } from "./context.js";
 import {
 	FlexTreeEntityKind,
 	type FlexTreeField,
+	type FlexTreeNode,
 	type FlexTreeOptionalField,
 	type FlexTreeRequiredField,
 	type FlexTreeSequenceField,
@@ -51,7 +53,7 @@ import {
 	flexTreeSlot,
 } from "./flexTreeTypes.js";
 import { LazyEntity } from "./lazyEntity.js";
-import { type LazyTreeNode, getOrCreateHydratedFlexTreeNode } from "./lazyNode.js";
+import { LazyTreeNode, getOrCreateHydratedFlexTreeNode } from "./lazyNode.js";
 import { indexForAt, treeStatusFromAnchorCache } from "./utilities.js";
 import { combineChunks } from "../chunked-forest/index.js";
 
@@ -231,21 +233,29 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 	 */
 	public getFieldPathForEditing(): NormalizedFieldUpPath {
 		if (!this.isFreed()) {
-			if (
-				// Only allow editing if we are the root document field...
-				(this.parent === undefined && this.anchor.fieldKey === rootFieldKey) ||
-				// ...or are under a node in the document
-				(this.parent !== undefined &&
-					treeStatusFromAnchorCache(this.parent.anchorNode) === TreeStatus.InDocument)
-			) {
+			// Only allow editing if we are the root document field...
+			if (this.parent === undefined && this.anchor.fieldKey === rootFieldKey) {
 				return this.getFieldPath();
 			}
+			if (this.parent !== undefined) {
+				const status = treeStatusFromAnchorCache(this.parent.anchorNode);
+				// ...or are under a node that is hydrated and not deleted
+				if (status === TreeStatus.InDocument || status === TreeStatus.Removed) {
+					return this.getFieldPath();
+				}
+			}
 		}
 
-		throw new UsageError("Editing only allowed on fields with TreeStatus.InDocument status");
+		throw new UsageError(
+			"Editing only allowed on the root field or on fields under nodes with TreeStatus.InDocument or TreeStatus.Removed status",
+		);
 	}
 
-	protected getEditor(): IDefaultEditBuilder<ITreeCursorSynchronous> {
+	protected getEditor(): DataEditor<
+		ITreeCursorSynchronous,
+		DetachedRootLocation,
+		DetachedRootsLocation
+	> {
 		return new MappedEditBuilder(
 			this.context.checkout.editor,
 			(cursor: ITreeCursorSynchronous) =>
@@ -254,6 +264,11 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 	}
 }
 
+function fieldFromNode(node: FlexTreeNode): FieldKey {
+	assert(node instanceof LazyTreeNode, "Invalid tree type");
+	return node.anchorNode.parentField;
+}
+
 export class LazySequence extends LazyField implements FlexTreeSequenceField {
 	public at(index: number): FlexTreeUnknownUnboxed | undefined {
 		const finalIndex = indexForAt(index, this.length);
@@ -268,32 +283,48 @@ export class LazySequence extends LazyField implements FlexTreeSequenceField {
 		return this.map((x) => x);
 	}
 
-	public editor: SequenceFieldEditBuilder<FlexibleFieldContent> = {
+	public editor: SequenceFieldEditor<FlexibleFieldContent, readonly FlexTreeNode[]> = {
 		insert: (index, newContent) => {
 			this.sequenceEditor().insert(index, cursorForMapTreeField(newContent));
 		},
 		remove: (index, count) => {
 			this.sequenceEditor().remove(index, count);
 		},
+		attach: (index, content) => {
+			const contentLocations: DetachedRootsLocation = content.map((node) => ({
+				field: fieldFromNode(node),
+				count: 1,
+			}));
+			this.sequenceEditor().attach(index, contentLocations);
+		},
 	};
 
-	private sequenceEditor(): SequenceFieldEditBuilder<ITreeCursorSynchronous> {
+	private sequenceEditor(): SequenceFieldEditor<
+		ITreeCursorSynchronous,
+		DetachedRootsLocation
+	> {
 		const fieldPath = this.getFieldPathForEditing();
 		return this.getEditor().sequenceField(fieldPath);
 	}
 }
 
 export class LazyValueField extends LazyField implements FlexTreeRequiredField {
-	public editor: ValueFieldEditBuilder<FlexibleNodeContent> = {
+	public editor: RequiredFieldEditor<FlexibleNodeContent, FlexTreeNode> = {
 		set: (newContent) => {
 			this.valueFieldEditor().set(cursorForMapTreeField([newContent]));
 		},
+		attach: (content) => {
+			const root = fieldFromNode(content);
+			this.valueFieldEditor().attach(root);
+		},
 	};
 
-	private valueFieldEditor(): ValueFieldEditBuilder<ITreeCursorSynchronous> {
+	private valueFieldEditor(): RequiredFieldEditor<
+		ITreeCursorSynchronous,
+		DetachedRootLocation
+	> {
 		const fieldPath = this.getFieldPathForEditing();
-		const fieldEditor = this.getEditor().valueField(fieldPath);
-		return fieldEditor;
+		return this.getEditor().valueField(fieldPath);
 	}
 
 	public get content(): FlexTreeUnknownUnboxed {
@@ -302,16 +333,27 @@ export class LazyValueField extends LazyField implements FlexTreeRequiredField {
 }
 
 export class LazyOptionalField extends LazyField implements FlexTreeOptionalField {
-	public editor: OptionalFieldEditBuilder<ExclusiveMapTree> = {
+	public editor: OptionalFieldEditor<MinimalMapTreeNodeView, FlexTreeNode> = {
 		set: (newContent, wasEmpty) => {
 			this.optionalEditor().set(
 				newContent !== undefined ? cursorForMapTreeField([newContent]) : newContent,
 				wasEmpty,
 			);
 		},
+		attach: (content, wasEmpty) => {
+			if (content === undefined) {
+				this.optionalEditor().clear(wasEmpty);
+			} else {
+				const root = fieldFromNode(content);
+				this.optionalEditor().attach(root, wasEmpty);
+			}
+		},
+		clear: (wasEmpty) => {
+			this.optionalEditor().clear(wasEmpty);
+		},
 	};
 
-	private optionalEditor(): OptionalFieldEditBuilder<ITreeCursorSynchronous> {
+	private optionalEditor(): OptionalFieldEditor<ITreeCursorSynchronous, DetachedRootLocation> {
 		const fieldPath = this.getFieldPathForEditing();
 		const fieldEditor = this.getEditor().optionalField(fieldPath);
 		return fieldEditor;

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

@@ -15,21 +15,21 @@ import {
 import type { FieldKey, ITreeCursorSynchronous } from "../../core/index.js";
 import type { FieldBatchCodec, FieldBatchEncodingContext } from "../chunked-forest/index.js";
 
-import { Format, ForestFormatVersion } from "./format.js";
+import { FormatV1, ForestFormatVersion } from "./format.js";
 import { brand } from "../../util/index.js";
 
 /**
  * Uses field cursors
  */
 export type FieldSet = ReadonlyMap<FieldKey, ITreeCursorSynchronous>;
-export type ForestCodec = IJsonCodec<FieldSet, Format, Format, FieldBatchEncodingContext>;
+export type ForestCodec = IJsonCodec<FieldSet, FormatV1, FormatV1, FieldBatchEncodingContext>;
 
 /**
  * Convert a MinimumVersionForCollab to a ForestFormatVersion.
  * @param clientVersion - The MinimumVersionForCollab to convert.
  * @returns The ForestFormatVersion that corresponds to the provided MinimumVersionForCollab.
  */
-function clientVersionToForestSummaryVersion(
+function clientVersionToForestSummaryFormatVersion(
 	clientVersion: MinimumVersionForCollab,
 ): ForestFormatVersion {
 	// Currently, forest summary codec only writes in version 1.
@@ -44,9 +44,9 @@ export function makeForestSummarizerCodec(
 	// TODO: AB#41865
 	// This needs to be updated to support multiple versions.
 	// The second version will be used to enable incremental summarization.
-	const writeVersion = clientVersionToForestSummaryVersion(options.minVersionForCollab);
-	return makeVersionedValidatedCodec(options, new Set([ForestFormatVersion.v1]), Format, {
-		encode: (data: FieldSet, context: FieldBatchEncodingContext): Format => {
+	const writeVersion = clientVersionToForestSummaryFormatVersion(options.minVersionForCollab);
+	return makeVersionedValidatedCodec(options, new Set([ForestFormatVersion.v1]), FormatV1, {
+		encode: (data: FieldSet, context: FieldBatchEncodingContext): FormatV1 => {
 			const keys: FieldKey[] = [];
 			const fields: ITreeCursorSynchronous[] = [];
 			for (const [key, value] of data) {
@@ -55,7 +55,7 @@ export function makeForestSummarizerCodec(
 			}
 			return { keys, fields: inner.encode(fields, context), version: writeVersion };
 		},
-		decode: (data: Format, context: FieldBatchEncodingContext): FieldSet => {
+		decode: (data: FormatV1, context: FieldBatchEncodingContext): FieldSet => {
 			const out: Map<FieldKey, ITreeCursorSynchronous> = new Map();
 			const fields = inner.decode(data.fields, context);
 			assert(data.keys.length === fields.length, 0x891 /* mismatched lengths */);
@@ -70,5 +70,5 @@ export function makeForestSummarizerCodec(
 export function getCodecTreeForForestFormat(
 	clientVersion: MinimumVersionForCollab,
 ): CodecTree {
-	return { name: "Forest", version: clientVersionToForestSummaryVersion(clientVersion) };
+	return { name: "Forest", version: clientVersionToForestSummaryFormatVersion(clientVersion) };
 }

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

@@ -3,15 +3,14 @@
  * Licensed under the MIT License.
  */
 
-import { bufferToString } from "@fluid-internal/client-utils";
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type {
 	IExperimentalIncrementalSummaryContext,
-	ISummaryTreeWithStats,
 	ITelemetryContext,
 } from "@fluidframework/runtime-definitions/internal";
+import type { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
 
 import type { CodecWriteOptions } from "../../codec/index.js";
 import {
@@ -27,12 +26,13 @@ import {
 	forEachField,
 	makeDetachedFieldIndex,
 } from "../../core/index.js";
-import type {
-	Summarizable,
-	SummaryElementParser,
-	SummaryElementStringifier,
+import {
+	VersionedSummarizer,
+	type Summarizable,
+	type SummaryElementParser,
+	type SummaryElementStringifier,
 } from "../../shared-tree-core/index.js";
-import { idAllocatorFromMaxId, type JsonCompatible } from "../../util/index.js";
+import { idAllocatorFromMaxId, readAndParseSnapshotBlob } from "../../util/index.js";
 // eslint-disable-next-line import-x/no-internal-modules
 import { chunkFieldSingle, defaultChunkPolicy } from "../chunked-forest/chunkTree.js";
 import {
@@ -46,24 +46,23 @@ import { type ForestCodec, makeForestSummarizerCodec } from "./codec.js";
 import {
 	ForestIncrementalSummaryBehavior,
 	ForestIncrementalSummaryBuilder,
-	forestSummaryContentKey,
 } from "./incrementalSummaryBuilder.js";
-import { TreeCompressionStrategyExtended } from "../treeCompressionUtils.js";
-import type { IFluidHandle } from "@fluidframework/core-interfaces";
-
-/**
- * The key for the tree that contains the overall forest's summary tree.
- * This tree is added by the parent of the forest summarizer.
- * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
- */
-export const forestSummaryKey = "Forest";
+import {
+	forestSummaryContentKey,
+	forestSummaryKey,
+	minVersionToForestSummaryFormatVersion,
+	supportedForestSummaryFormatVersions,
+	type ForestSummaryFormatVersion,
+} from "./summaryTypes.js";
+import { TreeCompressionStrategy } from "../treeCompressionUtils.js";
 
 /**
  * Provides methods for summarizing and loading a forest.
  */
-export class ForestSummarizer implements Summarizable {
-	public readonly key = forestSummaryKey;
-
+export class ForestSummarizer
+	extends VersionedSummarizer<ForestSummaryFormatVersion>
+	implements Summarizable
+{
 	private readonly codec: ForestCodec;
 
 	private readonly incrementalSummaryBuilder: ForestIncrementalSummaryBuilder;
@@ -81,11 +80,18 @@ export class ForestSummarizer implements Summarizable {
 		initialSequenceNumber: number,
 		shouldEncodeIncrementally: IncrementalEncodingPolicy = defaultIncrementalEncodingPolicy,
 	) {
+		super(
+			forestSummaryKey,
+			minVersionToForestSummaryFormatVersion(options.minVersionForCollab),
+			supportedForestSummaryFormatVersions,
+			true /* supportPreVersioningFormat */,
+		);
+
 		// TODO: this should take in CodecWriteOptions, and use it to pick the write version.
 		this.codec = makeForestSummarizerCodec(options, fieldBatchCodec);
 		this.incrementalSummaryBuilder = new ForestIncrementalSummaryBuilder(
 			encoderContext.encodeType ===
-				TreeCompressionStrategyExtended.CompressedIncremental /* enableIncrementalSummary */,
+				TreeCompressionStrategy.CompressedIncremental /* enableIncrementalSummary */,
 			(cursor: ITreeCursorSynchronous) => this.forest.chunkField(cursor),
 			shouldEncodeIncrementally,
 			initialSequenceNumber,
@@ -102,14 +108,15 @@ export class ForestSummarizer implements Summarizable {
 	 *
 	 * TODO: when perf matters, this should be replaced with a chunked async version using a binary format.
 	 */
-	public summarize(props: {
+	protected summarizeInternal(props: {
 		stringify: SummaryElementStringifier;
 		fullTree?: boolean;
 		trackState?: boolean;
 		telemetryContext?: ITelemetryContext;
 		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
-	}): ISummaryTreeWithStats {
-		const { stringify, fullTree = false, incrementalSummaryContext } = props;
+		builder: SummaryTreeBuilder;
+	}): void {
+		const { stringify, fullTree = false, incrementalSummaryContext, builder } = props;
 
 		const rootCursor = this.forest.getCursorAboveDetachedFields();
 		const fieldMap: Map<FieldKey, ITreeCursorSynchronous & ITreeSubscriptionCursor> =
@@ -132,6 +139,7 @@ export class ForestSummarizer implements Summarizable {
 			fullTree,
 			incrementalSummaryContext,
 			stringify,
+			builder,
 		});
 		const encoderContext: FieldBatchEncodingContext = {
 			...this.encoderContext,
@@ -143,13 +151,14 @@ export class ForestSummarizer implements Summarizable {
 		const encoded = this.codec.encode(fieldMap, encoderContext);
 		fieldMap.forEach((value) => value.free());
 
-		return this.incrementalSummaryBuilder.completeSummary({
+		this.incrementalSummaryBuilder.completeSummary({
 			incrementalSummaryContext,
 			forestSummaryContent: stringify(encoded),
+			builder,
 		});
 	}
 
-	public async load(
+	protected async loadInternal(
 		services: IChannelStorageService,
 		parse: SummaryElementParser,
 	): Promise<void> {
@@ -164,24 +173,23 @@ export class ForestSummarizer implements Summarizable {
 			0xc21 /* Forest summary content missing in snapshot */,
 		);
 
-		const readAndParseBlob = async <T extends JsonCompatible<IFluidHandle>>(
-			id: string,
-		): Promise<T> => {
-			const treeBuffer = await services.readBlob(id);
-			const treeBufferString = bufferToString(treeBuffer, "utf8");
-			return parse(treeBufferString) as T;
-		};
-
 		// Load the incremental summary builder so that it can download any incremental chunks in the
 		// snapshot.
-		await this.incrementalSummaryBuilder.load(services, readAndParseBlob);
+		await this.incrementalSummaryBuilder.load({
+			services,
+			readAndParseChunk: async (chunkBlobPath: string) =>
+				readAndParseSnapshotBlob(chunkBlobPath, services, parse),
+		});
 
 		// TODO: this code is parsing data without an optional validator, this should be defined in a typebox schema as part of the
 		// forest summary format.
-		const fields = this.codec.decode(await readAndParseBlob(forestSummaryContentKey), {
-			...this.encoderContext,
-			incrementalEncoderDecoder: this.incrementalSummaryBuilder,
-		});
+		const fields = this.codec.decode(
+			await readAndParseSnapshotBlob(forestSummaryContentKey, services, parse),
+			{
+				...this.encoderContext,
+				incrementalEncoderDecoder: this.incrementalSummaryBuilder,
+			},
+		);
 		const allocator = idAllocatorFromMaxId();
 		const fieldChanges: [FieldKey, DeltaFieldChanges][] = [];
 		const build: DeltaDetachedNodeBuild[] = [];

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

@@ -5,9 +5,9 @@
 
 import { type Static, Type } from "@sinclair/typebox";
 
-import { Versioned } from "../../codec/index.js";
 import { schemaFormatV1 } from "../../core/index.js";
 import { brand, type Brand } from "../../util/index.js";
+import { EncodedFieldBatch } from "../chunked-forest/index.js";
 
 /**
  * The format version for the forest.
@@ -29,10 +29,10 @@ const FormatGeneric = (
 		{
 			version: Type.Literal(version),
 			keys: Type.Array(schemaFormatV1.FieldKeySchema),
-			fields: Versioned,
+			fields: EncodedFieldBatch,
 		},
 		{ additionalProperties: false },
 	);
 
-export const Format = FormatGeneric(brand<ForestFormatVersion>(ForestFormatVersion.v1));
-export type Format = Static<typeof Format>;
+export const FormatV1 = FormatGeneric(brand<ForestFormatVersion>(ForestFormatVersion.v1));
+export type FormatV1 = Static<typeof FormatV1>;

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

@@ -4,10 +4,7 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import type {
-	IExperimentalIncrementalSummaryContext,
-	ISummaryTreeWithStats,
-} from "@fluidframework/runtime-definitions/internal";
+import type { IExperimentalIncrementalSummaryContext } from "@fluidframework/runtime-definitions/internal";
 import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
 import {
 	brand,
@@ -30,21 +27,7 @@ import type { ISnapshotTree } from "@fluidframework/driver-definitions/internal"
 import { LoggingError } from "@fluidframework/telemetry-utils/internal";
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import type { SummaryElementStringifier } from "../../shared-tree-core/index.js";
-
-/**
- * The key for the blob under ForestSummarizer's root.
- * This blob contains the ForestCodec's output.
- * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
- */
-export const forestSummaryContentKey = "ForestTree";
-
-/**
- * The contents of an incremental chunk is under a summary tree node with its {@link ChunkReferenceId} as the key.
- * The inline portion of the chunk content is encoded with the forest codec is stored in a blob with this key.
- * The rest of the chunk contents  is stored in the summary tree under the summary tree node.
- * See the summary format in {@link ForestIncrementalSummaryBuilder} for more details.
- */
-const chunkContentsBlobKey = "contents";
+import { chunkContentsBlobKey, forestSummaryContentKey } from "./summaryTypes.js";
 
 /**
  * State that tells whether a summary is currently being tracked.
@@ -299,11 +282,13 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 	 * contents of the chunks.
 	 * @param readAndParse - A function that reads and parses a blob from the storage service.
 	 */
-	public async load(
-		services: IChannelStorageService,
-		readAndParseChunk: <T extends JsonCompatible<IFluidHandle>>(id: string) => Promise<T>,
-	): Promise<void> {
-		const forestTree = services.getSnapshotTree?.();
+	public async load(args: {
+		services: IChannelStorageService;
+		readAndParseChunk: <T extends JsonCompatible<IFluidHandle>>(
+			chunkBlobPath: string,
+		) => Promise<T>;
+	}): Promise<void> {
+		const forestTree = args.services.getSnapshotTree?.();
 		// Snapshot tree should be available when loading forest's contents. However, it is an optional function
 		// and may not be implemented by the storage service.
 		if (forestTree === undefined) {
@@ -321,12 +306,13 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			for (const [chunkReferenceId, chunkSnapshotTree] of Object.entries(snapshotTree.trees)) {
 				const chunkSubTreePath = `${parentTreeKey}${chunkReferenceId}`;
 				const chunkContentsPath = `${chunkSubTreePath}/${chunkContentsBlobKey}`;
-				if (!(await services.contains(chunkContentsPath))) {
+				if (!(await args.services.contains(chunkContentsPath))) {
 					throw new LoggingError(
 						`SharedTree: Cannot find contents for incremental chunk ${chunkContentsPath}`,
 					);
 				}
-				const chunkContents = await readAndParseChunk<EncodedFieldBatch>(chunkContentsPath);
+				const chunkContents =
+					await args.readAndParseChunk<EncodedFieldBatch>(chunkContentsPath);
 				this.loadedChunksMap.set(chunkReferenceId, {
 					encodedContents: chunkContents,
 					summaryPath: chunkSubTreePath,
@@ -357,8 +343,9 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		fullTree: boolean;
 		incrementalSummaryContext: IExperimentalIncrementalSummaryContext | undefined;
 		stringify: SummaryElementStringifier;
+		builder: SummaryTreeBuilder;
 	}): ForestIncrementalSummaryBehavior {
-		const { fullTree, incrementalSummaryContext, stringify } = args;
+		const { fullTree, incrementalSummaryContext, stringify, builder } = args;
 		// If there is no incremental summary context, do not summarize incrementally. This happens in two scenarios:
 		// 1. When summarizing a detached container, i.e., the first ever summary.
 		// 2. When running GC, the default behavior is to call summarize on DDS without incrementalSummaryContext.
@@ -374,7 +361,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			summarySequenceNumber: incrementalSummaryContext.summarySequenceNumber,
 			latestSummaryBasePath: incrementalSummaryContext.summaryPath,
 			chunkSummaryPath: [],
-			parentSummaryBuilder: new SummaryTreeBuilder(),
+			parentSummaryBuilder: builder,
 			fullTree,
 			stringify,
 		};
@@ -469,25 +456,24 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 	 * @param incrementalSummaryContext - The context for the incremental summary that contains the sequence numbers.
 	 * If this is undefined, the summary tree will only contain a summary blob for `forestSummaryContent`.
 	 * @param forestSummaryContent - The stringified ForestCodec output of top-level Forest content.
+	 * @param builder - The summary tree builder to use to add the forest's contents. Note that if tracking an incremental
+	 * summary, this builder will be the same as the one tracked in `trackedSummaryProperties`.
 	 * @returns the Forest's summary tree.
 	 */
 	public completeSummary(args: {
 		incrementalSummaryContext: IExperimentalIncrementalSummaryContext | undefined;
 		forestSummaryContent: string;
-	}): ISummaryTreeWithStats {
-		const { incrementalSummaryContext, forestSummaryContent } = args;
+		builder: SummaryTreeBuilder;
+	}): void {
+		const { incrementalSummaryContext, forestSummaryContent, builder } = args;
 		if (!this.enableIncrementalSummary || incrementalSummaryContext === undefined) {
-			const summaryBuilder = new SummaryTreeBuilder();
-			summaryBuilder.addBlob(forestSummaryContentKey, forestSummaryContent);
-			return summaryBuilder.getSummaryTree();
+			builder.addBlob(forestSummaryContentKey, forestSummaryContent);
+			return;
 		}
 
 		validateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);
 
-		this.trackedSummaryProperties.parentSummaryBuilder.addBlob(
-			forestSummaryContentKey,
-			forestSummaryContent,
-		);
+		builder.addBlob(forestSummaryContentKey, forestSummaryContent);
 
 		// Copy over the entries from the latest summary to the current summary.
 		// In the current summary, there can be fields that haven't changed since the latest summary and the chunks
@@ -516,9 +502,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		}
 
 		this.forestSummaryState = ForestSummaryTrackingState.ReadyToTrack;
-		const summaryTree = this.trackedSummaryProperties.parentSummaryBuilder.getSummaryTree();
 		this.trackedSummaryProperties = undefined;
-		return summaryTree;
 	}
 
 	/**

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

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
-export { forestSummaryKey, ForestSummarizer } from "./forestSummarizer.js";
+export { ForestSummarizer } from "./forestSummarizer.js";
 export { getCodecTreeForForestFormat } from "./codec.js";
 export { ForestFormatVersion } from "./format.js";
+export { forestSummaryKey } from "./summaryTypes.js";

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

@@ -0,0 +1,61 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+
+/**
+ * The key for the tree that contains the overall forest's summary tree.
+ * This tree is added by the parent of the forest summarizer.
+ * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
+ */
+export const forestSummaryKey = "Forest";
+
+/**
+ * The key for the blob under ForestSummarizer's root.
+ * This blob contains the ForestCodec's output.
+ * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
+ */
+export const forestSummaryContentKey = "ForestTree";
+
+/**
+ * The contents of an incremental chunk is under a summary tree node with its {@link ChunkReferenceId} as the key.
+ * The inline portion of the chunk content is encoded with the forest codec is stored in a blob with this key.
+ * The rest of the chunk contents  is stored in the summary tree under the summary tree node.
+ * See the summary format in {@link ForestIncrementalSummaryBuilder} for more details.
+ */
+export const chunkContentsBlobKey = "contents";
+
+/**
+ * The versions for the forest summary.
+ */
+export enum ForestSummaryFormatVersion {
+	/**
+	 * This version represents summary format before summary versioning was introduced.
+	 */
+	v1 = 1,
+	/**
+	 * This version adds metadata to the summary. This is backward compatible with version 1.
+	 */
+	v2 = 2,
+	/**
+	 * The latest version of the summary. Must be updated when a new version is added.
+	 */
+	vLatest = v2,
+}
+
+export const supportedForestSummaryFormatVersions = new Set<ForestSummaryFormatVersion>([
+	ForestSummaryFormatVersion.v1,
+	ForestSummaryFormatVersion.v2,
+]);
+
+/**
+ * Returns the summary version to use as per the given minimum version for collab.
+ */
+export function minVersionToForestSummaryFormatVersion(
+	version: MinimumVersionForCollab,
+): ForestSummaryFormatVersion {
+	// Currently, version 2 is written which adds metadata blob to the summary.
+	return ForestSummaryFormatVersion.v2;
+}