feat(tree): add SchemaFactoryAlpha.stagedOptional for incremental required→optional field migration

[noencke]

Summary

• Adds SchemaFactoryAlpha.stagedOptional(T) to enable incremental migration of required fields to optional fields without a coordinated deployment
• During the staged rollout period, the field is Optional in the view schema (TypeScript type T | undefined) but the stored schema stays Required, so old clients are unaffected and writing undefined is blocked at runtime
• Mirrors the existing SchemaStaticsBeta.staged(T) pattern for allowed types, but for field optionality

Migration path: sf.required(T) → sf.stagedOptional(T) → sf.optional(T)

[Copilot]

Pull request overview

Adds a new “staged optional” field pattern to the SharedTree Simple Tree alpha schema API to support incremental required → optional migrations without coordinated deployments, by keeping the stored schema required during rollout while exposing optionality in the view schema.

Changes:

• Introduces SchemaFactoryAlpha.stagedOptional(...) (and supporting plumbing) to represent “optional-in-view, required-in-stored (until fully upgraded)” fields.
• Extends stored-schema generation options with includeStagedOptional(...) and updates view→stored transformation / discrepancy logic to account for staged optional compatibility.
• Adds end-to-end and compatibility tests covering the A(required) → B(staged optional) → C(optional) rollout path and unhydrated construction behavior.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/dds/tree/src/simple-tree/api/schemaFactoryAlpha.ts	Adds the stagedOptional schema factory API (static + instance) and docs.
packages/dds/tree/src/simple-tree/fieldSchema.ts	Plumbs a staged-optional marker through field props and exposes it via FieldSchemaAlpha.isOptionalStaged.
packages/dds/tree/src/simple-tree/simpleSchema.ts	Extends SimpleFieldSchema with isOptionalStaged marker metadata.
packages/dds/tree/src/simple-tree/core/toStored.ts	Adds includeStagedOptional to StoredFromViewSchemaGenerationOptions.
packages/dds/tree/src/simple-tree/toStoredSchema.ts	Threads includeStagedOptional through restrictive/permissive options and adjusts view→stored conversion to potentially force Required kind for staged optional.
packages/dds/tree/src/simple-tree/api/discrepancies.ts	Suppresses kind mismatch when viewing Required stored fields with staged-optional view fields.
packages/dds/tree/src/simple-tree/api/storedSchema.ts	Ensures persisted schema extraction does not include staged optional as optional in stored schema.
packages/dds/tree/src/test/simple-tree/api/stagedSchemaUpgrade.spec.ts	Adds migration-path tests (user API + compatibility tester + unhydrated construction).
packages/dds/tree/src/test/simple-tree/toStoredSchema.spec.ts	Updates tests for new stored-schema generation option shape.
packages/dds/tree/src/test/testTrees.ts	Updates test document schema generation options to include includeStagedOptional.
packages/dds/tree/api-report/tree.alpha.api.md	Updates alpha API report for new API surface.

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

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

Crawling...

Stats:
  279037 links
    1880 destination URLs
    2126 URLs ignored
       0 warnings
       0 errors