feat(tree): add persisted commit metadata

[Noah Encke (noencke)]

Description

Applications can now attach arbitrary, JSON-serializable metadata to the commit that a transaction produces, replicate it to collaborating clients, and persist it in the document.

Write it via the new customMetadata field on RunTransactionParamsAlpha:

view.runTransaction(
	() => {
		view.root.insertAtEnd("new item");
	},
	{ customMetadata: { author: "alice", intent: "add-item" } },
);

Read it back while walking the branch's history, via the new custom property on TreeBranchCommitMetadata:

for (
	let commit = view.branchHistory.getHead();
	commit !== undefined;
	commit = commit.getParent()
) {
	const metadata = commit.custom;
}

Because a commit may be produced by nested transactions, each of which may supply metadata, custom is the flattened combination of them all (outermost wins on conflicting keys). The structural view is available as commit.customTree, a CustomMetadataTree mirroring the transaction nesting — the same relationship labels.tree has to a change's label set.

The metadata lives directly on the commit — on GraphCommit.customMetadata in memory and inline on the commits in the EditManager summary. That is what makes its lifetime automatically match the commit's: once the commit is trimmed from the trunk, the metadata goes with it, so there is no separate index to populate, reconcile, or prune.

Both the op format and the summary format gain a v7 (MessageFormatVersion.v7 and EditManagerFormatVersion.v7), written only when minVersionForCollab is 2.117.0 or later (gated by FluidClientVersion.v2_117). That floor is a declaration rather than an enforcement mechanism: a client too old for v7 fails cleanly with an unsupported-version error when it reaches v7 data, so adopting this requires deploying v7-capable readers everywhere before raising the floor. The changeset spells out the rollout sequence.

A revert may now be performed inside a transaction provided it is that transaction's only change, which lets the revert be given its own metadata. Attempting any other change in such a transaction throws an error.

Reviewer Guidance

The review process is outlined on this wiki page.

The GraphCommit.customMetadata property is required, not optional

This is the load-bearing decision. Two places rebuild a commit from its parts rather than spreading it (mintCommit and rebaseBranch), and an optional property would let both silently drop the metadata. Declaring it required turns each into a compile error, so the type system enumerates every site that has to make a decision.

Where a rebuilt commit is the same logical commit as its source, the property is propagated. undefined is used only where a genuinely new commit is minted — the inverse commit produced by reverting, rollback commits, the synthetic root/trunk-base commits, and edits from the editor that a transaction has not yet annotated.

The metadata tree mirrors transaction nesting

Each transaction in a nested stack contributes a node to a CustomMetadataTree. The root node is the outermost transaction, and nested transactions add child nodes. Aborted nested transactions remove their node again, so they never contribute. The single commit produced by the stack carries the tree, from which the flattened custom view is derived.

Compatibility

The v7 codecs are only selected when minVersionForCollab >= 2.117.0, so nothing changes for existing clients by default. Evidence that this holds: regenerating the full snapshot corpus added new v2_117 directories and modified no existing snapshot file, meaning the v3/v4/v6 output is byte-for-byte unchanged.

If an application supplies metadata while configured below 2.117.0, the value is kept in memory for the local session but is neither replicated nor persisted. There is a test for this.

The version-specific typebox schemas exclude the customMetadata field for pre-v7 formats, so no pre-v7 encoder can write it. The two formats then differ in how strictly they validate, and deliberately so: the summary schemas were already additionalProperties: false, so a payload falsely claiming to be pre-v7 while carrying the field is rejected there. The op Message schema is left permissive, as it has always been — tightening the op envelope would risk rejecting ops over envelope properties unrelated to this feature, and belongs in its own PR — so such a payload is tolerated there instead. Both behaviors are covered by tests.

Breaking Changes

None. All new API surface is @alpha and additive.

[github-actions]

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (24671 lines, 114 files), I've queued these reviewers:

• Correctness — logic errors, race conditions, lifecycle issues
• Security — vulnerabilities, secret exposure, injection
• API Compatibility — breaking changes, release tags, type design
• Performance — algorithmic regressions, memory leaks
• Testing — coverage gaps, hollow tests

How this works

• Adjust the reviewer set by ticking/unticking boxes above. Reviewer toggles alone don't trigger anything.

• Tick Start review below to dispatch the review fleet.

• After review finishes, tick Start review again to request another run — it auto-resets after each dispatch.

• This comment updates as new commits land; your reviewer selections are preserved.

• Start review

[Noah Encke (noencke)]

Pushed d752c3cd addressing an internal review pass. Three substantive fixes:

1. Trimmed commits kept their metadata. Eviction poisons change/revision/parent on trimmed commits, but the newest trimmed commit deliberately survives as the reachable trunk base — so its metadata stayed readable even though it is never written to the summary. A client could therefore read metadata that a client loading from that summary would never see. The same gap let a TreeBranchCommitMetadata captured before trimming keep reporting metadata indefinitely. Metadata is now cleared for every trimmed commit (cleared rather than poisoned, so a stale wrapper reads undefined instead of throwing, and the value can be collected).

2. The commit aliased the caller's object, and could disagree with what was persisted. The metadata is now snapshotted at the transaction boundary via a JSON round trip. This fixes two things: mutating the object after runTransaction returns can no longer change an already-created commit (which mattered most on a fork, where submission can happen much later), and the value read back locally is now exactly what peers and summaries see instead of diverging on values with no JSON representation (\NaN\ read as \NaN\ locally but arrived as
ull\ remotely). Values that cannot be represented as a JSON object now throw a UsageError.

3. JsonCompatibleReadOnlyObjectSchema was Type.Any(), so the runtime schema accepted a primitive where the format declares an object. It now validates the object root.

Also added golden op/summary format tests that pin the serialized persistedMetadata key at v7 and assert its absence before v7 — the existing round-trip suites would have stayed green through a rename on both the encode and decode sides, silently orphaning metadata in documents already written at v7.

Two review points I deliberately did not act on, both documented in code so they are explicit choices rather than oversights:

• The metadata field is declared on the shared commit schema for all format versions, so a summary claiming to be v6 that nonetheless contained the field would be accepted rather than rejected as an additional property. Writing is correctly gated, and making the schema version-dependent would mean threading the version through every schema builder.
• SharedTreeBranch.apply takes the metadata as an optional parameter. Every current call site is correct (audited), and requiring it would churn many call sites where a genuinely new commit is being minted.

Suite is now 15304 passing / 1 failing, the failure being the pre-existing snapshotCompatibilityChecker Windows path-separator mismatch that also fails on unmodified \main.

[Noah Encke (noencke)]

Pushed b7706ae1 with all review feedback applied. Replied inline to each comment; summarizing the three that weren't purely mechanical:

Nested transaction merge - implemented. All transactions in the stack now contribute to the single commit they produce, outermost winning on conflicts. A nested transaction that is rolled back contributes nothing, which fell out of the existing commit/abort handling and seemed clearly right. Four new tests cover it.

JSON validation precedent - the closest existing case is persisted schema metadata (\PersistedMetadataFormat), which validates at the schema level only via \Type.Record(Type.String(), JsonCompatibleReadOnlySchema). I've aligned \JsonCompatibleReadOnlyObjectSchema\ to that exact shape; it had been \Type.Any(), weaker than the format it describes. I kept the snapshot step on top, since it fixes a real aliasing bug rather than just validating.

NaN - normalizing to
ull\ matches what SharedTree already does with user data (\leafNodeSchema.ts, and \SchemaStatics.number\ documents it as matching JSON's limitations), so this is consistent rather than novel. Docs now appeal to \JsonCompatibleReadOnlyObject\ instead of restating the rules.

One thing worth your call on naming: \persistedMetadata\ is already an established name in this package for exactly this concept - app-supplied \JsonCompatibleReadOnlyObject\ that gets persisted - on \FieldPropsAlpha, \NodeSchemaOptionsAlpha\ and \SimpleNodeSchemaBaseAlpha. So the rename does trade consistency with those options bags for consistency with \metadata.custom. I've made the change as requested since \custom\ clearly fits the read property; flagging it only in case the collision with the schema convention changes your mind for the write side.

Validation: 15306 passing / 1 failing (the pre-existing Windows path-separator failure). API reports regenerated - the diff is exactly the two renamed lines per report, no incidental churn. No snapshot files changed, since none of them carry metadata.

[Copilot]

Copilot reviewed 86 out of 86 changed files in this pull request and generated 2 comments.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Noah Encke (noencke)]

Did a pass over the tests themselves against completeness / convention / minimality / uniqueness. Pushed ff233283 and a77a9a2c.

Removed as redundant (3). Two Reading tests ("readable immediately", "undefined when unannotated") were fully subsumed by the test that checks metadata stays on its own commit across an unannotated neighbour, so that one now covers all three. The nested-transaction "outermost wins" test was subsumed by the three-level merge test, which already includes a property that conflicts at every level.

Added (2), both verified non-vacuous by breaking the behaviour and confirming the test fails:

• Reverting an annotated commit must not copy its metadata onto the new inverse commit. This is documented behaviour (undefined only for genuinely new commits) that nothing exercised. Confirmed it fails if the revert path passes the reverted commit's metadata through.
• An empty metadata object must survive replication rather than being treated as absent. Confirmed it fails if the encoder uses a truthiness check instead of an undefined check — a realistic way to regress this.

Minimality. Most tests needed neither replication nor persistence but were each standing up a TestTreeProviderLite, a view and an initialize. Those now use the existing getView helper (one line), with a small createConnectedViews helper for the ones that genuinely need peers. Net effect is 26 tests in ~13 fewer lines than the previous 27. In the codec tests I dropped an assertion implied by the deep-equal above it, and replaced counting "customMetadata": occurrences in the serialized string with a direct assertion on the encoded peer branch structure.

Organisation. The async transaction test was sitting under Nested transactions, and op rollback under Persistence; both moved.

Gaps I considered and deliberately left: metadata over a shared branch (vSharedBranches) is exercised only at the codec level, since that format is unreleased and test-only; and the detached-then-attached path is covered transitively, since submitCommit's detached branch passes the in-memory commit straight through and the attach summary uses the same encode path already under test. Happy to add either if you'd rather they were explicit.

Suite: 15305 passing, 1 failing (the pre-existing Windows path-separator failure).

[Joshua Smithrud (Josmithr)]

API and docs changes look good. I left one sanity-check question about one of the API changes. I did not review the code changes in detail.

[github-actions]

🔗 Found some broken links! 💔

Run a link check locally to find them. See Checking for Broken Links for more information.

linkcheck output

$ start-server-and-test "npm run serve -- --host 127.0.0.1 --no-open" http://127.0.0.1:3000 check-links
1: starting server using command "npm run serve -- --host 127.0.0.1 --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"


> fluid-framework-website@0.0.0 serve
> docusaurus serve --host 127.0.0.1 --no-open

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

> fluid-framework-website@0.0.0 check-links
> linkcheck http://127.0.0.1:3000 --skip-file skipped-urls.txt

Crawling...

http://127.0.0.1:3000/docs/data-structures/tree/schema-evolution/feature-flag-schema-upgrades
- (72:12) 'isStaged..' => http://127.0.0.1:3000/docs/api/fluid-framework/treeviewalpha-interface#isstagedupgradeenabled-methodsignature (HTTP 200 but missing anchor)


Stats:
  338443 links
    2041 destination URLs
    2297 URLs ignored
       1 warnings
       0 errors

Error: Command failed with exit code 1: npm run check-links
    at makeError (/home/runner/work/FluidFramework/FluidFramework/website/node_modules/.pnpm/execa@5.1.1/node_modules/execa/lib/error.js:60:11)
    at handlePromise (/home/runner/work/FluidFramework/FluidFramework/website/node_modules/.pnpm/execa@5.1.1/node_modules/execa/index.js:118:26)
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5) {
  shortMessage: 'Command failed with exit code 1: npm run check-links',
  command: 'npm run check-links',
  escapedCommand: '"npm run check-links"',
  exitCode: 1,
  signal: undefined,
  signalDescription: undefined,
  stdout: undefined,
  stderr: undefined,
  failed: true,
  timedOut: false,
  isCanceled: false,
  killed: false
}
[ELIFECYCLE] Command failed with exit code 1.

[github-actions]

Bundle size comparison

Base commit: 480ee6fdd33a385c035446f67ff104953bac9c86
Head commit: 6cdc934d22f267e81eb57a09d85d4a3dfab06489

Pending — Build - client packages is running. Results will appear here when the build completes.