feat(tree): implement persisted commit metadata

[Noah Encke (noencke)]

Implements persisted commit metadata for SharedTree per the design in PR #28047: applications can attach a JSON-serializable value to the commit produced by a transaction, have it replicated to peers and persisted inline on commits in the EditManager summary, and read it back by revision. The metadata shares the lifetime of its commit, so it is dropped automatically when the commit is trimmed from the trunk — no separate GC policy.

What changed

• Format + codecs (shared-tree-core): adds MessageFormatVersion.v7 and EditManagerFormatVersion.v7, both gated behind a new FluidClientVersion.v3_0, plus an optional persistedMetadata field on both message formats, on CommitBase/Commit/EncodedCommit, and on CommitMessage. encodeCommit/decodeCommit and both message codecs carry the field, writing it only at v7 or later.
• Lifecycle: a PersistedCommitMetadataIndex keyed by RevisionTag lives on SharedTreeCore and is shared by every checkout (including forks), so metadata recorded by a transaction on a fork is found when a merge submits the commit. It is populated/read across submitCommit, processMessagesCore, applyStashedOp and rollback (resubmit works because submitCommit reads the index, not the decoded op), and pruned on ancestryTrimmed. It is deliberately not stored on GraphCommit, because rebaseBranch rebuilds commits as fresh object literals and would silently drop it.
• Alpha API: RunTransactionParamsAlpha.persistedMetadata, UntypedTreeViewAlpha.getPersistedCommitMetadata(revision), RevisionTag exported as @alpha, and LocalChangeMetadata.revision so a changed event can be correlated to its metadata. Metadata from nested transactions resolves to the outermost transaction; a transaction that produces no commit (empty body or rollback) discards its metadata without throwing.

Validation

No validation could be run in this environment, and none is claimed. The sandbox has no package registry access and no node_modules, so the toolchain could not be obtained:

Command	Result
npx tsc --project ./tsconfig.json --noEmit (in packages/dds/tree)	fails — no node_modules; install blocked
npm install -g typescript --offline	npm error code ENOTCACHED (configured registry is an ADO feed returning 401; nothing cached)
Invoke-WebRequest https://registry.npmjs.org/typescript	ERR_SSL_SSL/TLS_ALERT_HANDSHAKE_FAILURE
corepack pnpm --version	fails downloading from registry.npmjs.org (same TLS failure)

Consequently the branch has not been compiled, no test has been executed, and API reports were not regenerated. Before merging, a reviewer must run, from packages/dds/tree:

pnpm build && pnpm test:mocha:esm
pnpm build:api-reports          # expected diffs listed below
pnpm test:snapshots:regen       # to confirm the hand-derived snapshots below

Required follow-up: API reports

api-report/*.api.md are generated artifacts and per .claude/CLAUDE.md must never be hand-edited, so they are not included here and CI will flag them as stale. Regenerating should add exactly: FluidClientVersion.v3_0, RunTransactionParamsAlpha.persistedMetadata, UntypedTreeViewAlpha.getPersistedCommitMetadata, RevisionTag, and LocalChangeMetadata.revision (and the corresponding re-exports in fluid-framework).

Snapshots

New snapshot files for the v3_0 client version were derived mechanically rather than generated, and should be verified with test:snapshots:regen. Every one is byte-identical to its v2_80 counterpart except for the single EditManager/Message format version field changing from 6 to 7 — which is exactly the delta observed between the existing v2_74 and v2_80 snapshot sets (4 → 6). Existing snapshots are untouched, because the codec tree records the write version and older minVersionForCollab values still write v6.

Scope

Scope: 72 changed files, one concern. 39 of those are the mechanically derived v3_0 snapshot files described above, and 1 is a changeset — 32 files carry real change.

The feature cannot be split. Landing the op codecs without the lifecycle wiring registers a format version with no producer; landing the summary persistence without the index leaves encodeCommit with nothing to read; landing the public API without either produces an alpha API that silently does nothing. Any intermediate slice would either be dead code or would advertise durability the document does not yet have.

Review map

Read in this order:

1. shared-tree-core/persistedCommitMetadata.ts — the index and the rationale for keying by revision.
2. shared-tree-core/sharedTreeCore.ts — all lifecycle wiring (submit / process / stash / rollback / trim).
3. shared-tree-core/editManagerFormatCommons.ts, messageFormat*.ts, messageTypes.ts — the format additions.
4. shared-tree-core/editManagerCodecsCommons.ts, messageCodec*.ts, *Codecs*.ts, codec/codec.ts, shared-tree/sharedTree.ts — codec plumbing and v7/v3_0 registration.
5. shared-tree/treeCheckout.ts — where a transaction's metadata is recorded. Note the non-obvious part: the transaction stack mints the squash commit's revision lazily on the first edit, and SharedTreeCore submits from the branch's beforeChange during apply, so the recording hook is the revision minter (mintTransactionRevisionTag) rather than a branch event. discardPendingPersistedMetadata cleans up the abort / no-commit cases.
6. simple-tree/api/tree.ts, simple-tree/api/transactionTypes.ts, core/rebase/types.ts, index.ts, entrypoints/alpha.ts — the alpha surface.
7. test/shared-tree/persistedCommitMetadata.spec.ts and the two version-list additions in existing codec tests — everything else is generated/mechanical.

Alternatives considered: putting the metadata on GraphCommit (loses data on the first rebase — see above), and a separately persisted index blob (needs its own GC policy and can drift from the trunk). A feature-flagged partial landing was rejected because the flag would be minVersionForCollab itself, which is already the gate this design uses.

Test coverage

test/shared-tree/persistedCommitMetadata.spec.ts covers: local readback; undefined for un-annotated commits; peer replication; survival across rebase behind a concurrent remote commit; metadata dropped from the wire when minVersionForCollab is too old; nested transactions resolving to the outermost; no-change and rolled-back transactions discarding metadata without throwing; and fork → merge → peer, including after the fork is disposed. The spec's summary round-trip, trailing-op, retainHistory, trimming, disconnect/resubmit and stashed-op scenarios are not yet covered by direct tests; the code paths are implemented but those cases need the async TestTreeProvider harness and should be added once the suite can actually be executed.

Authored with Minions.

[Copilot]

Pull request overview

Implements persisted, replicated commit metadata for SharedTree commits (keyed by RevisionTag) by introducing new v7 message/edit-manager formats gated behind FluidClientVersion.v3_0, wiring an in-memory PersistedCommitMetadataIndex through submit/process/stash/rollback/trim paths, and exposing an @alpha API to attach/read metadata.

Changes:

• Adds PersistedCommitMetadataIndex and threads it through SharedTreeCore + TreeCheckout so metadata survives fork→merge and is pruned on trunk trimming.
• Introduces MessageFormatVersion.v7 / EditManagerFormatVersion.v7 (write-enabled at minVersionForCollab >= 3.0.0) and carries optional persistedMetadata through op + summary codecs.
• Exposes alpha API surface (RunTransactionParamsAlpha.persistedMetadata, UntypedTreeViewAlpha.getPersistedCommitMetadata, LocalChangeMetadata.revision, RevisionTag export) with new tests and v3_0 snapshot baselines.

Reviewed changes

Copilot reviewed 72 out of 72 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
.changeset/persisted-commit-metadata.md	Release note for persisted commit metadata feature and usage example.
packages/dds/tree/src/codec/codec.ts	Adds FluidClientVersion.v3_0 gating for new v7 formats.
packages/dds/tree/src/core/rebase/types.ts	Exports RevisionTag as @alpha and adds LocalChangeMetadata.revision.
packages/dds/tree/src/entrypoints/alpha.ts	Re-exports RevisionTag on the alpha entrypoint.
packages/dds/tree/src/index.ts	Re-exports RevisionTag at package root.
packages/dds/tree/src/shared-tree/schematizingTreeView.ts	Plumbs getPersistedCommitMetadata through SchematizingSimpleTreeView.
packages/dds/tree/src/shared-tree/sharedTree.ts	Wires persisted-metadata index into checkout creation; maps v7 dependent format versions.
packages/dds/tree/src/shared-tree/treeCheckout.ts	Records transaction metadata against minted revisions; exposes getPersistedCommitMetadata; shares index across forks.
packages/dds/tree/src/shared-tree-core/editManager.ts	Exposes EditManager trimming events for metadata pruning.
packages/dds/tree/src/shared-tree-core/editManagerCodecs.ts	Adds v7 edit-manager codec entry and passes persisted-metadata index into codecs.
packages/dds/tree/src/shared-tree-core/editManagerCodecsCommons.ts	Encodes/decodes optional persistedMetadata via shared index (write at v7+ only).
packages/dds/tree/src/shared-tree-core/editManagerCodecsV1toV4.ts	Adds persisted-metadata option plumbing and gates writing by format version.
packages/dds/tree/src/shared-tree-core/editManagerCodecsVSharedBranches.ts	Enables persisted metadata in shared-branches codec path (always write for that experimental format).
packages/dds/tree/src/shared-tree-core/editManagerFormatCommons.ts	Adds persistedMetadata field to commit encodings; introduces EditManagerFormatVersion.v7.
packages/dds/tree/src/shared-tree-core/editManagerFormatV1toV4.ts	Extends edit-manager version union to include v7.
packages/dds/tree/src/shared-tree-core/index.ts	Re-exports PersistedCommitMetadataIndex and PersistedCommitMetadata.
packages/dds/tree/src/shared-tree-core/messageCodecV1ToV4.ts	Adds v7-aware encoding/decoding of persistedMetadata (write only at v7+).
packages/dds/tree/src/shared-tree-core/messageCodecVSharedBranches.ts	Adds encode/decode support for persistedMetadata in shared-branches messages.
packages/dds/tree/src/shared-tree-core/messageCodecs.ts	Registers v7 message codec gated behind FluidClientVersion.v3_0.
packages/dds/tree/src/shared-tree-core/messageFormat.ts	Introduces MessageFormatVersion.v7 and marks it supported.
packages/dds/tree/src/shared-tree-core/messageFormatV1ToV4.ts	Adds optional persistedMetadata field and includes v7 in version union.
packages/dds/tree/src/shared-tree-core/messageFormatVSharedBranches.ts	Adds optional persistedMetadata field to shared-branches message schema.
packages/dds/tree/src/shared-tree-core/messageTypes.ts	Adds persistedMetadata?: JsonCompatibleReadOnlyObject to CommitMessage.
packages/dds/tree/src/shared-tree-core/persistedCommitMetadata.ts	Adds PersistedCommitMetadataIndex (revision-keyed) and metadata type alias.
packages/dds/tree/src/shared-tree-core/sharedTreeCore.ts	Creates shared metadata index; prunes on trim; populates from ops/summaries; supports rollback/stash/resubmit paths.
packages/dds/tree/src/simple-tree/api/transactionTypes.ts	Adds RunTransactionParamsAlpha.persistedMetadata alpha API surface.
packages/dds/tree/src/simple-tree/api/tree.ts	Adds UntypedTreeViewAlpha.getPersistedCommitMetadata(revision) alpha API surface.
packages/dds/tree/src/test/shared-tree-core/edit-manager/editManagerCodecs.test.ts	Adds v7 to codec version test lists.
packages/dds/tree/src/test/shared-tree-core/messageCodec.spec.ts	Adds v7 to codec version test lists.
packages/dds/tree/src/test/shared-tree/persistedCommitMetadata.spec.ts	New spec exercising local readback, peer replication, rebasing, version gating, nested tx, rollback/no-op, fork/merge.
packages/dds/tree/src/test/snapshots/output/codec-tree/MinVersionForCollab.v3_0.json	New codec-tree snapshot reflecting v3_0 write versions.
packages/dds/tree/src/test/snapshots/output/op-format/v3_0/field change.json	New v3_0 op-format snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/op-format/v3_0/schema change.json	New v3_0 op-format snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/attachment-tree-final.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/competing-removes-index-0.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/competing-removes-index-1.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/competing-removes-index-2.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/competing-removes-index-3.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/complete-3x3-final.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/concurrent-inserts-tree2.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/concurrent-inserts-tree3.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/empty-root-final.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/has-handle-final.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/insert-and-remove-tree-0-after-insert.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/insert-and-remove-tree-0-final.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/insert-and-remove-tree-1-final.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/move-across-fields-tree-0-final.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/nested-sequence-change-final.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/optional-field-scenarios-final.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Compressed/v3_0/tree-with-identifier-field-final.json	New v3_0 compressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/attachment-tree-final.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/competing-removes-index-0.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/competing-removes-index-1.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/competing-removes-index-2.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/competing-removes-index-3.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/complete-3x3-final.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/concurrent-inserts-tree2.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/concurrent-inserts-tree3.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/empty-root-final.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/has-handle-final.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/insert-and-remove-tree-0-after-insert.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/insert-and-remove-tree-0-final.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/insert-and-remove-tree-1-final.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/move-across-fields-tree-0-final.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/nested-sequence-change-final.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/optional-field-scenarios-final.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/snapshots/output/summary/Uncompressed/v3_0/tree-with-identifier-field-final.json	New v3_0 uncompressed summary snapshot (format v7).
packages/dds/tree/src/test/shared-tree/summary-load-snapshots/singleTree-Compressed-v3_0-1.json	New summary-load baseline for compressed v3_0.
packages/dds/tree/src/test/shared-tree/summary-load-snapshots/singleTree-Uncompressed-v3_0-1.json	New summary-load baseline for uncompressed v3_0.
packages/dds/tree/src/test/utils.ts	Updates test checkout mock surface to include new API entrypoint.
packages/dds/tree/src/util/index.ts	Re-exports JsonCompatibleReadOnlyObjectSchema.
packages/dds/tree/src/util/utils.ts	Adds JsonCompatibleReadOnlyObjectSchema for object-only JSON-like validation.

---

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

[github-actions]

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

Based on the diff (16863 lines, 72 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)]

VERDICT: REQUEST_CHANGES

Persisted metadata can diverge between clients, is not discoverable for remote changes, and is retained after its owning fork is discarded; the public API reports and critical durability tests are also missing, and the client build is currently failing.

Evidence and agent context

Blocking

1. packages/dds/tree/src/shared-tree-core/persistedCommitMetadata.ts:35-43 — the index stores and returns application objects by reference. Mutating either the object passed to runTransaction or the object returned by getPersistedCommitMetadata changes only that client's future lookup/summary while peers retain the already-serialized value, so the same revision can have different persisted metadata across clients. Required: take an owned deep snapshot on ingestion and prevent callers from mutating indexed state (for example, return a defensive clone), with a cross-client mutation test.
2. packages/dds/tree/src/shared-tree/treeCheckout.ts:956-963 — remote changed events expose no revision, while UntypedTreeViewAlpha.getPersistedCommitMetadata requires one and its docs state revisions come from change events (simple-tree/api/tree.ts:421-434). Receiving applications therefore cannot discover or read metadata replicated from another client. Required: expose/populate the relevant remote commit revision(s), or deliver the associated metadata through the remote event API.
3. packages/dds/tree/src/shared-tree/treeCheckout.ts:1553-1564 — disposing an unmerged fork drops its commits without removing their entries from the tree-wide metadata index; those revisions never reach trunk trimming. Repeated speculative forks leak metadata indefinitely and leave metadata readable after the commit no longer exists. Required: track fork-owned revisions and release entries when an unmerged fork is disposed, while preserving entries for commits that were merged.
4. packages/dds/tree/api-report/tree.alpha.api.md and packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md — neither generated API report changed despite the new alpha export/members (RevisionTag, LocalChangeMetadata.revision, RunTransactionParamsAlpha.persistedMetadata, and UntypedTreeViewAlpha.getPersistedCommitMetadata). Required: regenerate and commit both packages' API reports; do not hand-edit them.
5. packages/dds/tree/src/test/shared-tree/persistedCommitMetadata.spec.ts:1-280 — the tests never round-trip a summary, and they do not exercise the newly changed stashed-op/disconnect-resubmit paths. That leaves the feature's defining durability behavior and two explicit lifecycle integrations unverified. Required: add at least summary load/round-trip and disconnect/resubmit or stashed-op coverage for annotated commits.

Minimum change to approve: make metadata ownership and fork cleanup deterministic, provide a usable remote correlation path, add the critical persistence/lifecycle tests, regenerate API reports, and restore the client build.

• Checks: gh pr checks 28063 --repo microsoft/FluidFramework — fail (Build - client packages); npm --prefix packages\dds\tree run build:esnext and npm --prefix packages\dds\tree run build:test:esm — blocked (tsc unavailable because dependencies are absent); npm --prefix packages\dds\tree run test:mocha:esm -- --grep "persisted commit metadata" — blocked (mocha unavailable); npm --prefix packages\dds\tree run build:api-reports — blocked (concurrently unavailable).
• Repository review skill: review invoked

Repo harnesses used

• Runtime: copilot
• Instructions: .github/copilot-instructions.md
• Skills used: review
• Skills loaded: api-changes, ci-readiness-check, comparison-base, fluid-pr, fluid-pr-guide, fluid-release, pipeline-test-triage, policy-check, review-pr-local, trigger-pipelines-for-copilot-pr
• Agents used: general-purpose (unknown)

Review by Minions (Ripley — Lead / Explorer · gpt-5.6-sol)

[github-actions]

Bundle size comparison

Base commit: unresolved
Head commit: adb3b84344ab3f16f563baacf67068d3b1d20a18

⚠️ Comparison unavailable.

The PR's CI build failed — fix the build and the comment will update once the next run succeeds.

[Noah Encke (noencke)]

Premature - ignore.