Align @experimental emitterScope with the standard scope convention

[JoshLove-msft]

Problem

TypeSpec.HttpClient.@experimental uses options.emitterScope to control which emitters receive its lifecycle metadata:

@experimental(#{ emitterScope: "@typespec/http-client-csharp" })
op test(): void;

This differs from the established client-generator decorator convention, which uses a top-level optional argument named scope:

extern dec clientName(
  target: unknown,
  rename: valueof string,
  scope?: valueof string
);

@experimental and ClientDecoratorOptions.emitterScope were introduced together in #11094 with a package-specific scope parser.

Impact

TCGC's generic decorator handling automatically filters decorators by decoratorInfo.arguments.scope. It cannot recognize the nested decoratorInfo.arguments.options.emitterScope value used by @experimental.

As a result, emitters consuming @experimental through TCGC's generic decorator metadata must implement a second scope parser and filtering path. This creates duplicated behavior and makes the two scoping conventions easier to interpret differently over time.

Proposed compatibility path

Align @experimental with the standard top-level scope convention without immediately breaking existing TypeSpec:

1. Add an optional top-level scope argument to @experimental.
2. Continue accepting options.emitterScope as a deprecated compatibility alias.
3. Use scope when provided; otherwise fall back to options.emitterScope.
4. Report a diagnostic if both values are supplied.
5. Update examples and documentation to use scope.
6. Remove emitterScope only in a future breaking release.

Possible shape:

@experimental(
  #{ diagnosticId: "C", dependsOn: #["A", "B"] },
  "@typespec/http-client-csharp"
)
op test(): void;

Acceptance criteria

• New usage follows the standard top-level scope convention.
• Existing options.emitterScope usage continues to compile during the compatibility period.
• TCGC automatically filters the decorator without emitter-specific scope parsing.
• Supplying both scope forms produces a clear diagnostic.
• Existing include/exclude behavior remains unchanged.
• Documentation describes the migration and deprecation.

Related work

• Original implementation: [http-client-csharp] Fix sub-client endpoint type when root endpoint is a hostname string #11094
• Experimental metadata enhancement: Add diagnostic metadata to @experimental #11684
• C# emitter integration: Emit experimental diagnostics in C# clients #11685
• Experimental diagnostic design: Enhance @experimental with diagnostic IDs and dependencies #11690

[github-actions]

🎯 Issue Triage

This is a feature request to align @experimental's scoping argument with the standard top-level scope convention used by other client-generator decorators, addressing an incompatibility with TCGC's generic decorator filtering.

Category: Feature Request
Area: emitter:client:all

🔍 Analysis

• @experimental uses options.emitterScope (nested inside an options object) while all other client decorators use a top-level scope?: valueof string argument.
• TCGC's generic decorator handling filters by decoratorInfo.arguments.scope, so it cannot see decoratorInfo.arguments.options.emitterScope, forcing emitters to implement custom scope filtering for @experimental.
• The proposal adds a top-level scope parameter with backward-compatible fallback to options.emitterScope during a deprecation window.
• Related PRs: [http-client-csharp] Fix sub-client endpoint type when root endpoint is a hostname string #11094 (original implementation), Add diagnostic metadata to @experimental #11684, Emit experimental diagnostics in C# clients #11685, Enhance @experimental with diagnostic IDs and dependencies #11690.

📝 Suggested next steps

• Add top-level scope argument to @experimental decorator signature
• Emit deprecation diagnostic when options.emitterScope is used
• Emit error diagnostic when both scope and options.emitterScope are supplied
• Update TCGC filtering so it picks up @experimental without custom parsing
• Update documentation and examples to use scope
• Plan emitterScope removal for a future breaking release

Generated by Agentic Triage