Add Tree.tagContentSchema helper

[noencke]

See the changeset for details

[Copilot]

Pull Request Overview

This PR adds a new Tree.ensureSchema helper function to the alpha API that allows developers to explicitly tag insertable content with a schema type, resolving ambiguity when the same object structure could match multiple schemas. The implementation introduces a new schemaSymbol that gets attached to objects to indicate their intended schema.

Key changes:

• Added schemaSymbol and TreeAlpha.ensureSchema to help disambiguate content that matches multiple schemas
• Modified getPossibleTypes to respect the schemaSymbol when determining compatible schemas
• Added comprehensive test coverage for the new functionality

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md	Exported schemaSymbol and added ensureSchema method to TreeAlpha interface
packages/dds/tree/api-report/tree.alpha.api.md	Exported schemaSymbol and added ensureSchema method to TreeAlpha interface
packages/dds/tree/src/simple-tree/core/withType.ts	Defined the new schemaSymbol with documentation
packages/dds/tree/src/simple-tree/core/index.ts	Exported schemaSymbol from the core module
packages/dds/tree/src/simple-tree/index.ts	Re-exported schemaSymbol from the simple-tree module
packages/dds/tree/src/index.ts	Re-exported schemaSymbol from the main tree package
packages/dds/tree/src/simple-tree/unhydratedFlexTreeFromInsertable.ts	Modified getPossibleTypes to check for and respect the schemaSymbol property
packages/dds/tree/src/shared-tree/treeAlpha.ts	Implemented the ensureSchema function that tags content with the schema symbol
packages/dds/tree/src/test/simple-tree/unhydratedFlexTreeFromInsertable.spec.ts	Added tests for getPossibleTypes with the type symbol
packages/dds/tree/src/test/simple-tree/api/treeNodeApi.spec.ts	Added comprehensive tests for the ensureSchema API
.changeset/tricky-shirts-sleep.md	Added changeset documenting the new feature

[Josmithr]

I'm assuming there's no additional type-narrowing that we can provide here? The content is already InsertableField<TSchema>, there's just the potential for ambiguity that we're now preventing by tacking on the symbol.

[noencke]

I'm not sure I understand your question. Are you thinking that we could e.g. have the return type be the type + the symbol?

[Josmithr]

Not specifically. I was just musing that it might be neat if we could differentiate between insertable content that might be ambiguous vs insertable content that is not ambiguous at the type-level. I think currently the answer is no. And since nowhere else in our system is that distinction made at the type-level, I don't think it makes sense to introduce something like that here. But maybe a future consideration.

[noencke]

Oh yea. That would be cool. Got me thinking if it's possible... maybe? You transform the input type union into a tuple with some TS trickery, and then check if the tuple has a length > 1?

[github-actions]

🔗 Found some broken links! 💔

Run a link check locally to find them. See
https://github.com/microsoft/FluidFramework/wiki/Checking-for-broken-links-in-the-documentation for more information.

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

 ELIFECYCLE  Command failed with exit code 1.