(tree) Add version FieldBatchFormatVersion.v2 for FieldBatchCodec #25811

agarwal-navin · 2025-11-04T22:49:23Z

Description

Added a new version v2 to FieldBatchFormatVersion. This new version will be used for FieldBatchCodec when minVersionForCollab is >= 2.72.0. Incremental summaries will be enabled for FieldBatchFormatVersion.v2 and later - a follow up PR will make necessary changes to forest summarizer for this. This change adds validation that the FieldBatchFormatVersion is v2 when incremental encoding / decoding is used.

Added stronger typing FieldBatchFormatVersion in places where number was used for field batch codec versions.

Updated the codec snapshot tests to run for FieldBatchFormatVersion versions v1 and v2. Added smoke tests for FieldBatchFormatVersion v2.

packages/dds/tree/src/test/feature-libraries/chunked-forest/codec/schemaBasedEncode.spec.ts

packages/dds/tree/src/test/feature-libraries/chunked-forest/codec/compressedEncode.spec.ts

packages/dds/tree/src/feature-libraries/chunked-forest/codec/formatGeneric.ts

Copilot

Pull Request Overview

This PR introduces version 2 of the FieldBatchFormatVersion to support incremental encoding in the tree data structure. The change adds a new FluidClientVersion (v2_72) that enables the new encoding format, while maintaining backward compatibility with version 1.

Key changes:

Adds FieldBatchFormatVersion.v2 and corresponding type definitions (EncodedFieldBatchV1, EncodedFieldBatchV2)
Introduces FluidClientVersion.v2_72 which maps to the new v2 format
Updates codec logic to select appropriate encoding functions based on the write version
Adds version checks to ensure incremental encoding is only used with v2 or higher

Reviewed Changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
format.ts	Defines v2 constant and creates separate type schemas for v1 and v2 formats
codecs.ts	Implements version mapping logic and selects encoding functions based on target version
codec.ts	Adds FluidClientVersion.v2_72 constant
compressedEncode.ts	Adds version assertion for incremental encoding to enforce v2 requirement
chunkDecoding.ts	Adds version assertion for incremental decoding to enforce v2 requirement
schemaBasedEncode.ts	Splits encoding function into v1/v2 variants and passes version to context
uncompressedEncode.ts	Splits encoding function into v1/v2 variants accepting version parameter
Various test files	Updates tests to use brand() with version constants and adds version-specific test coverage

packages/dds/tree/src/codec/codec.ts

packages/dds/tree/src/feature-libraries/forest-summary/format.ts

agarwal-navin · 2025-11-06T00:32:38Z

packages/dds/tree/src/feature-libraries/forest-summary/format.ts

-	},
-	{ additionalProperties: false },
-);
+const FormatGeneric = <TVersion extends ForestFormatVersion>(


Added this to change the type of version from number to ForestFormatVersion.
This makes the usage type safe. Caught this problem when debugging tests that were passing a number to this and the compiler didn't complain.

CraigMacomber · 2025-11-06T18:40:45Z

packages/dds/tree/src/feature-libraries/chunked-forest/codec/codecs.ts

 ): FieldBatchFormatVersion {
-	// Currently, field batch codec only writes in version 1.
-	return brand(FieldBatchFormatVersion.v1);
+	return clientVersion < FluidClientVersion.v2_72


I thought we would have a more unified system where every codec would specify its different formats with encoders and decoders and what versions they were first supported by, and some shared code would use that to select write version from client version and optional overrides.

Is there some common utility this should be using? At the runtime levels we have the config maps stuff which does this kind of selection: we should have a codec layer build on top of that which this should be using?

I'm not sure on the status of our multi version codecs, but I think we have enough logic in them that it would be worth using it here and in makeFieldBatchCodec for consistency.

I would like to use the ClientVersionDispatchingCodecBuilder which all codecs should use as a centralized way to do this. Preferable they use similar pattern as the runtime does. I plan to do that separately for all the codecs.

CraigMacomber · 2025-11-06T18:43:16Z

packages/dds/tree/src/feature-libraries/chunked-forest/codec/format.ts


-export const EncodedFieldBatch = EncodedFieldBatchGeneric(
-	FieldBatchFormatVersion.v1,
+export const EncodedFieldBatchV1 = EncodedFieldBatchGeneric(


Likely not worth it in this case, but one way we fond in the past to make the PRs more incremental and targeted for this kind of change is to do the rename to v1 in its own change, and setting up of the versioning as well. Thos can be done independent of adding the second version.

Makes sense. I will leave this PR as is though because this one is simple enough.

CraigMacomber · 2025-11-06T18:48:04Z

packages/dds/tree/src/feature-libraries/chunked-forest/codec/formatGeneric.ts


 /**
 * Format for encoding a tree chunk.
 * @param version - format version. Must be changed if there is any change to the generic schema, or the `shape` schema.


Suggested change

* @param version - format version. Must be changed if there is any change to the generic schema, or the `shape` schema.

* @param version - format version. Must be changed if there is any change to the generic schema, or the `shape` schema:

equivalently must be changed if the previously existing decode logic will not correctly handle the new encoding.

* If adding a new encoding version which does not use this function,

* this parameter should be retyped to be a union of the subset of FieldBatchFormatVersion values which this supports.

Updated the comment with a few tweaks.

CraigMacomber · 2025-11-06T18:53:00Z

packages/dds/tree/src/feature-libraries/chunked-forest/codec/formatGeneric.ts

-	extends Static<typeof EncodedFieldBatchBase> {
+export interface EncodedFieldBatchGeneric<
+	TEncodedShape,
+	TVersion extends FieldBatchFormatVersion = FieldBatchFormatVersion,


is capturing this as a type parameter actually useful? Do we have any code which requires it? I suspect typing version as just FieldBatchFormatVersion would be fine and simpler.

You are right. FieldBatchFormatVersion is enough here.

github-actions · 2025-11-06T21:56:04Z

🔗 Found some broken links! 💔

Run a link check locally to find them. See
https://github.com/microsoft/FluidFramework/wiki/Checking-for-broken-links-in-the-documentation for more information.

linkcheck output


> [email protected] ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> [email protected] serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> [email protected] check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

 ELIFECYCLE  Command failed with exit code 1.

Copilot AI review requested due to automatic review settings November 4, 2025 22:49

agarwal-navin requested a review from a team as a code owner November 4, 2025 22:49

agarwal-navin requested review from CraigMacomber and yann-achard-MS November 4, 2025 22:49

github-actions bot added area: dds Issues related to distributed data structures area: dds: tree public api change Changes to a public API base: main PRs targeted against main branch labels Nov 4, 2025

agarwal-navin commented Nov 4, 2025

View reviewed changes

packages/dds/tree/src/test/feature-libraries/chunked-forest/codec/schemaBasedEncode.spec.ts Show resolved Hide resolved

agarwal-navin commented Nov 4, 2025

View reviewed changes

packages/dds/tree/src/test/feature-libraries/chunked-forest/codec/compressedEncode.spec.ts Show resolved Hide resolved

agarwal-navin commented Nov 4, 2025

View reviewed changes

packages/dds/tree/src/feature-libraries/chunked-forest/codec/formatGeneric.ts Outdated Show resolved Hide resolved

Copilot AI reviewed Nov 4, 2025

View reviewed changes

packages/dds/tree/src/codec/codec.ts Outdated Show resolved Hide resolved

agarwal-navin commented Nov 4, 2025

View reviewed changes

packages/dds/tree/src/feature-libraries/forest-summary/format.ts Outdated Show resolved Hide resolved

agarwal-navin changed the title ~~(tree) Add version FieldBatchFormatVersion.v2 for fieldBatchCodec~~ (tree) Add version FieldBatchFormatVersion.v2 for FieldBatchCodec Nov 5, 2025

github-actions bot added the area: framework Framework is a tag for issues involving the developer framework. Eg Aqueduct label Nov 5, 2025

agarwal-navin added 2 commits November 5, 2025 11:11

(tree) Add version FieldBatchFormatVersion.v2 for fieldBatchCodec

d4b63fe

fluid-framework api.md

0314dfc

agarwal-navin force-pushed the revEncodedFieldBatchFormat branch from 05bef8d to 0314dfc Compare November 5, 2025 21:46

Update format type

df98fa9

agarwal-navin commented Nov 6, 2025

View reviewed changes

Comment for 2.72.0 update

000927a

CraigMacomber reviewed Nov 6, 2025

View reviewed changes

agarwal-navin added 2 commits November 6, 2025 13:44

PR feedback

8b76983

Update snapshot files

70fde78

- * @param version - format version. Must be changed if there is any change to the generic schema, or the `shape` schema.
+ * @param version - format version. Must be changed if there is any change to the generic schema, or the `shape` schema:
+ equivalently must be changed if the previously existing decode logic will not correctly handle the new encoding.
+ * If adding a new encoding version which does not use this function,
+ * this parameter should be retyped to be a union of the subset of FieldBatchFormatVersion values which this supports.

(tree) Add version FieldBatchFormatVersion.v2 for FieldBatchCodec #25811

Are you sure you want to change the base?

(tree) Add version FieldBatchFormatVersion.v2 for FieldBatchCodec #25811

Conversation

agarwal-navin commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CraigMacomber Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Nov 6, 2025

linkcheck output

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

agarwal-navin commented Nov 4, 2025 •

edited

Loading

CraigMacomber Nov 6, 2025 •

edited

Loading