feat(tree): runtime schema upgrade mechanism

[jenn-le]

Description

Adds runtime support for enabling selected staged schema upgrades in SharedTree.

This updates TreeView.initialize and TreeView.upgradeSchema to accept an optional upgrades property bag. Applications can use this to control when staged schema upgrades are included in stored schema, which makes it easier to separate code rollout from schema rollout and to test future document shapes before enabling them broadly.

This also adds test coverage for enabling staged allowed type upgrades and staged optional field upgrades through the new API parameter.

Reviewer Guidance

The review process is outlined on this wiki page.

The main area to review is the runtime schema upgrade path in SharedTree, especially the handling of explicit upgrade targets when the default schema compatibility result is already equivalent.

[Copilot]

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

[github-actions]

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

Based on the diff (572 lines, 8 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

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

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

Crawling...

Stats:
  290922 links
    1934 destination URLs
    2184 URLs ignored
       0 warnings
       0 errors