feat(tree): add stagedOptionalRecursive

[noencke]

Description

Follow-up to #26918 (stagedOptional). Adds recursive versions of the methods.

Changes:

stagedOptionalRecursive — Adds the recursive-type variant of stagedOptional on SchemaStaticsAlpha and SchemaFactoryAlpha (instance + static). Follows the same pattern as optionalRecursive/requiredRecursive/withDefaultRecursive: relaxes type constraints via ImplicitAllowedTypesUnsafe and returns FieldSchemaAlphaUnsafe. The implementation simply casts the non-recursive stagedOptional function, matching the withDefaultRecursive pattern.

Reviewer Guidance

The review process is outlined on this wiki page.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a “staged optional” field mode to support incremental required→optional migrations and introduces the recursive-typing variant, plus updates schema conversion and compatibility logic to recognize staged optional fields.

Changes:

• Add SchemaFactoryAlpha.stagedOptional and SchemaFactoryAlpha.stagedOptionalRecursive (and corresponding statics) and plumb staged-optional metadata through schemas.
• Extend stored-schema generation to optionally treat staged-optional fields as optional via includeStagedOptional.
• Add/adjust tests and API reports/changesets to reflect the new alpha API surface and behavior.

Reviewed changes

Copilot reviewed 14 out of 14 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 stagedOptional/stagedOptionalRecursive APIs and implementation.
packages/dds/tree/src/simple-tree/core/toStored.ts	Extends stored-from-view generation options with includeStagedOptional.
packages/dds/tree/src/simple-tree/toStoredSchema.ts	Implements staged-optional kind selection for stored schema generation.
packages/dds/tree/src/simple-tree/simpleSchema.ts	Adds isStagedOptional to SimpleFieldSchema with detailed semantics.
packages/dds/tree/src/simple-tree/fieldSchema.ts	Adds stagedOptionalUpgrade props and exposes isStagedOptional getter.
packages/dds/tree/src/simple-tree/api/discrepancies.ts	Suppresses kind discrepancies for staged-optional vs required stored during rollout.
packages/dds/tree/src/simple-tree/api/storedSchema.ts	Wires includeStagedOptional when extracting persisted schema.
packages/dds/tree/src/test/simple-tree/api/stagedSchemaUpgrade.spec.ts	Adds staged-optional upgrade tests and renames existing describe.
packages/dds/tree/src/test/simple-tree/toStoredSchema.spec.ts	Updates callers for new includeStagedOptional option.
packages/dds/tree/src/test/testTrees.ts	Updates stored-schema generation options in test documents.
packages/dds/tree/api-report/tree.alpha.api.md	API report updates for new staged optional APIs/fields.
packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md	API report updates for staged optional fields and extractor churn.
.changeset/fruity-cars-tell.md	Changeset for stagedOptional.
.changeset/brave-owls-jump.md	Changeset for stagedOptionalRecursive.

Comments suppressed due to low confidence (1)

packages/dds/tree/src/simple-tree/toStoredSchema.ts:1

• The current isStagedOptional preservation logic drops the explicit false value (it only preserves values that are instanceof SchemaUpgrade). This loses the documented distinction between false (“view schema field, not staged optional”) and undefined (“stored schema field”), which can cause downstream logic that relies on !== false checks (e.g., discrepancy suppression) to misclassify non-staged fields as staged optional. Preserve false as well when preservesViewData(options) is true (e.g., by passing through f.isStagedOptional instead of filtering to only SchemaUpgrade instances).

/*!

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

> fluid-framework-docs-site@0.0.0 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"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

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

> fluid-framework-docs-site@0.0.0 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

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

> fluid-framework-docs-site@0.0.0 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"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

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

> fluid-framework-docs-site@0.0.0 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