@fluidframework/tree 2.74.0-365691 → 2.74.0

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

@@ -4,12 +4,20 @@
  */
 
 /**
- * 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.
@@ -18,7 +26,7 @@
  */
 export type IncrementalEncodingPolicy = (
 	nodeIdentifier: string | undefined,
-	fieldKey: string,
+	fieldKey?: string,
 ) => boolean;
 
 /**
@@ -26,7 +34,7 @@ export type IncrementalEncodingPolicy = (
  */
 export const defaultIncrementalEncodingPolicy: IncrementalEncodingPolicy = (
 	nodeIdentifier: string | undefined,
-	fieldKey: string,
+	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 */);

package/src/feature-libraries/default-schema/defaultFieldKinds.ts

@@ -21,7 +21,6 @@ import {
 	FlexFieldKind,
 	type FullSchemaPolicy,
 	type ToDelta,
-	allowsTreeSchemaIdentifierSuperset,
 	referenceFreeFieldChangeRebaser,
 } from "../modular-schema/index.js";
 import {
@@ -76,15 +75,20 @@ export interface RequiredFieldEditor extends FieldEditor<OptionalChangeset> {
 }
 
 const optionalIdentifier = brandConst("Optional")<FieldKindIdentifier>();
+const requiredIdentifier = brandConst("Value")<FieldKindIdentifier>();
+const sequenceIdentifier = brandConst("Sequence")<FieldKindIdentifier>();
+const identifierFieldIdentifier = brandConst("Identifier")<FieldKindIdentifier>();
 
 /**
  * 0 or 1 items.
  */
 export const optional = new FlexFieldKind(optionalIdentifier, Multiplicity.Optional, {
 	changeHandler: optionalChangeHandler,
-	allowsTreeSupersetOf: (types, other) =>
-		(other.kind === sequence.identifier || other.kind === optionalIdentifier) &&
-		allowsTreeSchemaIdentifierSuperset(types, other.types),
+	allowMonotonicUpgradeFrom: new Set([
+		identifierFieldIdentifier,
+		requiredIdentifier,
+		forbiddenFieldKindIdentifier,
+	]),
 });
 
 export const requiredFieldEditor: RequiredFieldEditor = {
@@ -103,51 +107,38 @@ export const requiredFieldChangeHandler: FieldChangeHandler<
 	editor: requiredFieldEditor,
 };
 
-const requiredIdentifier = brandConst("Value")<FieldKindIdentifier>();
-
 /**
  * Exactly one item.
  */
 export const required = new FlexFieldKind(requiredIdentifier, Multiplicity.Single, {
 	changeHandler: requiredFieldChangeHandler,
-	allowsTreeSupersetOf: (types, other) =>
-		// By omitting Identifier here,
-		// this is making a policy choice that a schema upgrade cannot be done from required to identifier.
-		// Since an identifier can be upgraded into a required field,
-		// preventing the inverse helps ensure that schema upgrades are monotonic.
-		// Which direction is allowed is a subjective policy choice.
-		(other.kind === sequence.identifier ||
-			other.kind === requiredIdentifier ||
-			other.kind === optional.identifier) &&
-		allowsTreeSchemaIdentifierSuperset(types, other.types),
+	allowMonotonicUpgradeFrom: new Set([identifierFieldIdentifier]),
 });
 
-const sequenceIdentifier = brandConst("Sequence")<FieldKindIdentifier>();
-
 /**
  * 0 or more items.
  */
 export const sequence = new FlexFieldKind(sequenceIdentifier, Multiplicity.Sequence, {
 	changeHandler: sequenceFieldChangeHandler,
-	allowsTreeSupersetOf: (types, other) =>
-		other.kind === sequenceIdentifier &&
-		allowsTreeSchemaIdentifierSuperset(types, other.types),
+	allowMonotonicUpgradeFrom: new Set([
+		required.identifier,
+		optional.identifier,
+		identifierFieldIdentifier,
+		forbiddenFieldKindIdentifier,
+	]),
 });
 
-const identifierFieldIdentifier = brandConst("Identifier")<FieldKindIdentifier>();
-
 /**
  * Exactly one identifier.
  */
 export const identifier = new FlexFieldKind(identifierFieldIdentifier, Multiplicity.Single, {
 	changeHandler: noChangeHandler,
-	allowsTreeSupersetOf: (types, other) =>
-		// Allows upgrading from identifier to required: which way this upgrade is allowed to go is a subjective policy choice.
-		(other.kind === sequence.identifier ||
-			other.kind === requiredIdentifier ||
-			other.kind === optional.identifier ||
-			other.kind === identifierFieldIdentifier) &&
-		allowsTreeSchemaIdentifierSuperset(types, other.types),
+	// By omitting required here,
+	// this is making a policy choice that a schema upgrade cannot be done from required to identifier.
+	// Since an identifier can be upgraded into a required field,
+	// preventing the inverse helps ensure that schema upgrades are monotonic.
+	// Which direction is allowed is a subjective policy choice.
+	allowMonotonicUpgradeFrom: new Set([]),
 });
 
 /**
@@ -183,9 +174,7 @@ export const forbidden = new FlexFieldKind(
 	Multiplicity.Forbidden,
 	{
 		changeHandler: noChangeHandler,
-		// All multiplicities other than Value support empty.
-		allowsTreeSupersetOf: (types, other) =>
-			fieldKinds.get(other.kind)?.multiplicity !== Multiplicity.Single,
+		allowMonotonicUpgradeFrom: new Set(),
 	},
 );
 

package/src/feature-libraries/detachedFieldIndexSummarizer.ts

@@ -7,44 +7,91 @@ import { bufferToString } from "@fluid-internal/client-utils";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type {
 	IExperimentalIncrementalSummaryContext,
-	ISummaryTreeWithStats,
 	ITelemetryContext,
+	MinimumVersionForCollab,
 } from "@fluidframework/runtime-definitions/internal";
-import { createSingleBlobSummary } from "@fluidframework/shared-object-base/internal";
+import type { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
 
 import type { DetachedFieldIndex } from "../core/index.js";
-import type {
-	Summarizable,
-	SummaryElementParser,
-	SummaryElementStringifier,
+import {
+	type Summarizable,
+	type SummaryElementParser,
+	type SummaryElementStringifier,
+	VersionedSummarizer,
 } from "../shared-tree-core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 
 /**
  * The storage key for the blob in the summary containing schema data
  */
-const detachedFieldIndexBlobKey = "DetachedFieldIndexBlob";
+export const detachedFieldIndexBlobKey = "DetachedFieldIndexBlob";
 
 /**
- * Provides methods for summarizing and loading a tree index.
+ * The versions for the detached field index summary format.
+ */
+export const enum DetachedFieldIndexSummaryFormatVersion {
+	/**
+	 * 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,
+}
+
+const supportedVersions = new Set<DetachedFieldIndexSummaryFormatVersion>([
+	DetachedFieldIndexSummaryFormatVersion.v1,
+	DetachedFieldIndexSummaryFormatVersion.v2,
+]);
+
+/**
+ * Returns the summary version to use as per the given minimum version for collab.
  */
-export class DetachedFieldIndexSummarizer implements Summarizable {
-	public readonly key = "DetachedFieldIndex";
+function minVersionToDetachedFieldIndexSummaryFormatVersion(
+	version: MinimumVersionForCollab,
+): DetachedFieldIndexSummaryFormatVersion {
+	// Currently, version 2 is written which adds metadata blob to the summary.
+	return DetachedFieldIndexSummaryFormatVersion.v2;
+}
 
-	public constructor(private readonly detachedFieldIndex: DetachedFieldIndex) {}
+/**
+ * Provides methods for summarizing and loading a tree index.
+ */
+export class DetachedFieldIndexSummarizer
+	extends VersionedSummarizer<DetachedFieldIndexSummaryFormatVersion>
+	implements Summarizable
+{
+	public constructor(
+		private readonly detachedFieldIndex: DetachedFieldIndex,
+		minVersionForCollab: MinimumVersionForCollab,
+	) {
+		super(
+			"DetachedFieldIndex",
+			minVersionToDetachedFieldIndexSummaryFormatVersion(minVersionForCollab),
+			supportedVersions,
+			true,
+		);
+	}
 
-	public summarize(props: {
+	protected summarizeInternal(props: {
 		stringify: SummaryElementStringifier;
 		fullTree?: boolean;
 		trackState?: boolean;
 		telemetryContext?: ITelemetryContext;
 		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
-	}): ISummaryTreeWithStats {
+		builder: SummaryTreeBuilder;
+	}): void {
+		const { stringify, builder } = props;
 		const data = this.detachedFieldIndex.encode();
-		return createSingleBlobSummary(detachedFieldIndexBlobKey, props.stringify(data));
+		builder.addBlob(detachedFieldIndexBlobKey, stringify(data));
 	}
 
-	public async load(
+	protected async loadInternal(
 		services: IChannelStorageService,
 		parse: SummaryElementParser,
 	): Promise<void> {

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

@@ -5,17 +5,27 @@
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+import {
+	getConfigForMinVersionForCollab,
+	lowestMinVersionForCollab,
+} from "@fluidframework/runtime-utils/internal";
 
 import {
 	type CodecTree,
 	type CodecWriteOptions,
+	FluidClientVersion,
 	type IJsonCodec,
 	makeVersionedValidatedCodec,
 } from "../../codec/index.js";
 import type { FieldKey, ITreeCursorSynchronous } from "../../core/index.js";
 import type { FieldBatchCodec, FieldBatchEncodingContext } from "../chunked-forest/index.js";
 
-import { Format, ForestFormatVersion } from "./format.js";
+import {
+	ForestFormatVersion,
+	validVersions,
+	type Format,
+	FormatCommon,
+} from "./formatCommon.js";
 import { brand } from "../../util/index.js";
 
 /**
@@ -29,11 +39,15 @@ export type ForestCodec = IJsonCodec<FieldSet, Format, Format, FieldBatchEncodin
  * @param clientVersion - The MinimumVersionForCollab to convert.
  * @returns The ForestFormatVersion that corresponds to the provided MinimumVersionForCollab.
  */
-function clientVersionToForestSummaryVersion(
+export function clientVersionToForestFormatVersion(
 	clientVersion: MinimumVersionForCollab,
 ): ForestFormatVersion {
-	// Currently, forest summary codec only writes in version 1.
-	return brand(ForestFormatVersion.v1);
+	return brand(
+		getConfigForMinVersionForCollab(clientVersion, {
+			[lowestMinVersionForCollab]: ForestFormatVersion.v1,
+			[FluidClientVersion.v2_74]: ForestFormatVersion.v2,
+		}),
+	);
 }
 
 export function makeForestSummarizerCodec(
@@ -41,11 +55,9 @@ export function makeForestSummarizerCodec(
 	fieldBatchCodec: FieldBatchCodec,
 ): ForestCodec {
 	const inner = fieldBatchCodec;
-	// 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, {
+	const writeVersion = clientVersionToForestFormatVersion(options.minVersionForCollab);
+	const formatSchema = FormatCommon(writeVersion);
+	return makeVersionedValidatedCodec(options, validVersions, formatSchema, {
 		encode: (data: FieldSet, context: FieldBatchEncodingContext): Format => {
 			const keys: FieldKey[] = [];
 			const fields: ITreeCursorSynchronous[] = [];
@@ -70,5 +82,5 @@ export function makeForestSummarizerCodec(
 export function getCodecTreeForForestFormat(
 	clientVersion: MinimumVersionForCollab,
 ): CodecTree {
-	return { name: "Forest", version: clientVersionToForestSummaryVersion(clientVersion) };
+	return { name: "Forest", version: clientVersionToForestFormatVersion(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 {
@@ -42,31 +42,38 @@ import {
 	type IncrementalEncodingPolicy,
 } from "../chunked-forest/index.js";
 
-import { type ForestCodec, makeForestSummarizerCodec } from "./codec.js";
+import {
+	clientVersionToForestFormatVersion,
+	type ForestCodec,
+	makeForestSummarizerCodec,
+} from "./codec.js";
 import {
 	ForestIncrementalSummaryBehavior,
 	ForestIncrementalSummaryBuilder,
-	forestSummaryContentKey,
 } from "./incrementalSummaryBuilder.js";
+import {
+	minVersionToForestSummaryFormatVersion,
+	getForestRootSummaryContentKey,
+} from "./summaryTypes.js";
 import { TreeCompressionStrategy } 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 { ForestFormatVersion } from "./formatCommon.js";
+import {
+	ForestSummaryFormatVersion,
+	forestSummaryKey,
+	supportedForestSummaryFormatVersions,
+} from "./summaryFormatCommon.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;
+	private readonly forestRootSummaryContentKey: string;
 
 	/**
 	 * @param encoderContext - The schema if provided here must be mutated by the caller to keep it up to date.
@@ -81,11 +88,32 @@ export class ForestSummarizer implements Summarizable {
 		initialSequenceNumber: number,
 		shouldEncodeIncrementally: IncrementalEncodingPolicy = defaultIncrementalEncodingPolicy,
 	) {
-		// TODO: this should take in CodecWriteOptions, and use it to pick the write version.
+		super(
+			forestSummaryKey,
+			minVersionToForestSummaryFormatVersion(options.minVersionForCollab),
+			supportedForestSummaryFormatVersions,
+			true /* supportPreVersioningFormat */,
+		);
+
 		this.codec = makeForestSummarizerCodec(options, fieldBatchCodec);
+
+		const forestFormatWriteVersion = clientVersionToForestFormatVersion(
+			options.minVersionForCollab,
+		);
+		const summaryFormatWriteVersion = minVersionToForestSummaryFormatVersion(
+			options.minVersionForCollab,
+		);
+		this.forestRootSummaryContentKey = getForestRootSummaryContentKey(
+			summaryFormatWriteVersion,
+		);
+
+		// Incremental summary is supported from ForestFormatVersion.v2 and ForestSummaryFormatVersion.v3 onwards.
+		const enableIncrementalSummary =
+			forestFormatWriteVersion >= ForestFormatVersion.v2 &&
+			summaryFormatWriteVersion >= ForestSummaryFormatVersion.v3 &&
+			encoderContext.encodeType === TreeCompressionStrategy.CompressedIncremental;
 		this.incrementalSummaryBuilder = new ForestIncrementalSummaryBuilder(
-			encoderContext.encodeType ===
-				TreeCompressionStrategy.CompressedIncremental /* enableIncrementalSummary */,
+			enableIncrementalSummary,
 			(cursor: ITreeCursorSynchronous) => this.forest.chunkField(cursor),
 			shouldEncodeIncrementally,
 			initialSequenceNumber,
@@ -102,14 +130,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 +161,7 @@ export class ForestSummarizer implements Summarizable {
 			fullTree,
 			incrementalSummaryContext,
 			stringify,
+			builder,
 		});
 		const encoderContext: FieldBatchEncodingContext = {
 			...this.encoderContext,
@@ -143,45 +173,48 @@ 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),
+			forestSummaryRootContent: stringify(encoded),
+			forestSummaryRootContentKey: this.forestRootSummaryContentKey,
+			builder,
 		});
 	}
 
-	public async load(
+	protected async loadInternal(
 		services: IChannelStorageService,
 		parse: SummaryElementParser,
+		version: ForestSummaryFormatVersion | undefined,
 	): Promise<void> {
-		// The contents of the top-level forest must be present under a summary blob named `forestSummaryContentKey`.
+		// Get the key of the summary blob where the top-level forest content is stored based on the summary format version.
 		// If the summary was generated as `ForestIncrementalSummaryBehavior.SingleBlob`, this blob will contain all
 		// of forest's contents.
 		// If the summary was generated as `ForestIncrementalSummaryBehavior.Incremental`, this blob will contain only
 		// the top-level forest node's contents.
 		// The contents of the incremental chunks will be in separate tree nodes and will be read later during decoding.
+		const forestSummaryRootContentKey = getForestRootSummaryContentKey(version);
 		assert(
-			await services.contains(forestSummaryContentKey),
+			await services.contains(forestSummaryRootContentKey),
 			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(forestSummaryRootContentKey, 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 → formatCommon.ts}

@@ -5,22 +5,23 @@
 
 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 { strictEnum, type Values } from "../../util/index.js";
+import { EncodedFieldBatch } from "../chunked-forest/index.js";
 
 /**
  * The format version for the forest.
  */
-export const ForestFormatVersion = {
+export const ForestFormatVersion = strictEnum("ForestFormatVersion", {
 	v1: 1,
-} as const;
-export type ForestFormatVersion = Brand<
-	(typeof ForestFormatVersion)[keyof typeof ForestFormatVersion],
-	"ForestFormatVersion"
->;
+	/** This format supports incremental encoding */
+	v2: 2,
+});
+export type ForestFormatVersion = Values<typeof ForestFormatVersion>;
 
-const FormatGeneric = (
+export const validVersions = new Set([...Object.values(ForestFormatVersion)]);
+
+export const FormatCommon = (
 	version: ForestFormatVersion,
 	// Return type is intentionally derived.
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -29,10 +30,8 @@ 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 type Format = Static<ReturnType<typeof FormatCommon>>;

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

@@ -0,0 +1,12 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { Static } from "@sinclair/typebox";
+
+import { brand } from "../../util/index.js";
+import { FormatCommon, ForestFormatVersion } from "./formatCommon.js";
+
+export const FormatV1 = FormatCommon(brand<ForestFormatVersion>(ForestFormatVersion.v1));
+export type FormatV1 = Static<typeof FormatV1>;

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

@@ -0,0 +1,12 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { Static } from "@sinclair/typebox";
+
+import { brand } from "../../util/index.js";
+import { FormatCommon, ForestFormatVersion } from "./formatCommon.js";
+
+export const FormatV2 = FormatCommon(brand<ForestFormatVersion>(ForestFormatVersion.v2));
+export type FormatV2 = Static<typeof FormatV2>;