feat: add optional generation control extension

[SunSi12138]

Background

SharpLink can independently replace dynamic module generations on Client and Server, but caller-side generated artifacts and server-side implementation generations have no optional reconciliation contract between endpoints. Issue #691 proposes keeping that coordination outside Protocol v2 and the ordinary data path.

Changes

• add the optional SharpLink.GenerationControl package with a statically generated ISharpLinkGenerationControl RPC contract
• add queryable desired/actual inventory, stage, activate, and revision-based watch invalidation
• add stable generation identity/descriptor/state/result DTOs, including wire identity, generated ABI identity, artifact hash/reference, compatibility metadata, and explicit process-replacement capability
• add ISharpLinkGenerationProvider as the thin application materialization boundary
• keep artifact download, signature verification, version solving, rollout policy, automatic rollback, ALC loading, and NativeAOT process replacement outside the package
• wire the package into solution/package/public-API/release validation and NuGet package smoke
• document JIT and NativeAOT reconciliation semantics and the provider/authority boundaries
• keep the repository's reviewed eng/public-api/2.0.0 surface baseline for the 2.x line, while opting the new package out of a NuGet 2.0.0 package baseline because SharpLink.GenerationControl first ships after 2.0.0

Validation

Local executable validation is unavailable in this environment because no .NET SDK/toolchain can be installed. Repository CI is the executable validation path.

Two self-review rounds are required on the final code:

1. engineering/compile review: imports, project-reference policy, package dependency shape, generator/analyzer wiring, package smoke, release/public-API gates, docs, generated-manifest XML documentation, and compatibility impact
2. Issue acceptance review: desired/actual source of truth, stage/activate separation, watch as invalidation only, provider boundary, JIT/NativeAOT behavior, and initial-scope/non-goals

The final head is validated through the repository's existing PR Fast, PR Package Smoke, CodeQL, Codec Padding Security Evidence, and PR Extended workflows. Current-head results and any CI-driven fixes are recorded in the PR conversation and GitHub Checks so this description does not retain stale SHA-specific status after base updates.

Issue acceptance mapping

• inventory/state discovery: SharpLinkGenerationInventory
• desired generation reconciliation: queryable Desired and Actual sets with monotonic revision
• stage: StageAsync
• activate: ActivateAsync
• watch/notification: WatchAsync(afterRevision, ...), documented as invalidation rather than source of truth
• artifact transport remains separate: ISharpLinkGenerationProvider only materializes application-owned artifacts
• NativeAOT: ProcessReplacementRequired is explicit; no unknown managed assembly loading is implied
• core protocol/data path: unchanged

Fixes #691

[SunSi12138]

CI fix resolved

Failure cause:

• PR Package Smoke failed in Run Package Smoke because the ordinary package-smoke client attempted client.Get<ISharpLinkGenerationControl>() against a server that intentionally does not implement or advertise the optional generation-control contract.
• SharpLink correctly rejected that acquisition before RPC payload exchange; the failure was in the smoke scenario, not the new package/runtime behavior.

Fix:

• removed the invalid remote proxy acquisition from the ordinary transport smoke.
• retained package-surface coverage through contract reflection, [RpcContract] verification, DTO construction, generator compilation, package validation, and reviewed public-API verification.

Verification on final head bc8532200258052e163a563b46441f1fd9ce8194:

• PR Fast: success
• PR Package Smoke: success
• CodeQL: success
• Codec Padding Security Evidence: success
• PR Extended: success
• PR Extended covered Debug/Release build, integration tests, NativeAOT smoke, pack/package verification, NuGet package smoke, demo/load smoke, and desktop codec compatibility.

Local executable validation was not available because this environment cannot install the .NET SDK/toolchain; existing repository CI provided the executable validation.

[SunSi12138]

Rebased onto current dev without adding a merge commit.

• dev advanced to 2658b6b68ee78ffd3e3839e457227c0dcd1fffcc for the 2.0.1 release line.
• The PR remains one focused commit, now c8f8b21219643b5614055a1adaa609eeea960485.
• Preserved the repository's frozen eng/public-api/2.0.0 review baseline as intended for 2.x.
• Adapted the new SharpLink.GenerationControl package for first release on 2.0.1 by clearing PackageValidationBaselineVersion in that project only, because no published SharpLink.GenerationControl 2.0.0 package exists for NuGet baseline comparison.
• Merged the current 2.0.1 CHANGELOG.md and Directory.Build.props changes instead of overwriting them.

The PR is open, Ready, mergeable, based on the current dev, and still contains one commit. Repository CI is being rerun on the rebased head before declaring it ready again.

[SunSi12138]

Final CI follow-up on c8f8b21219643b5614055a1adaa609eeea960485

A PR Fast run triggered by the PR-description edit failed once in Unit Tests.

Failure cause:

• exact failing test: StaticClusterReconnectShouldBeSingleFlightAtTheProviderBoundary
• exact error: endpoint static-first has no active reconnect owner
• the test and its reconnect-support helper are byte-identical to current dev (same blob SHAs), and this PR does not modify Client reconnect code
• an earlier PR Fast run on this exact head had already passed all Unit Tests, so this was treated as a non-deterministic existing reconnect test race rather than a GenerationControl regression

What changed:

• no production/test code was changed for this unrelated transient failure
• the failed fast job was re-run unchanged through GitHub Actions

Validation:

• the re-run Unit Tests passed, followed by Generator Tests and the remainder of PR Fast; the workflow is now success
• PR Package Smoke: success on 2.0.1, including build, pack, package contracts, reviewed public API, and package consumption smoke
• CodeQL: success
• Codec Padding Security Evidence: success
• PR Extended: success on the rebased final head, including Debug/Release builds, integration tests, NativeAOT transport/topology smoke, pack/package verification, NuGet package smoke, demo/load smoke, and desktop codec compatibility

The PR remains one focused commit on the current 2.0.1 dev baseline.

[SunSi12138]

Rebased again onto the latest dev after #714.

• Previous head: c8f8b21219643b5614055a1adaa609eeea960485
• Current base: fa69e6c886ac882eb16425933ca0f6c09d1b46fc
• Current head: 5df13e2c1c8dd720c0da2c232fb3dd719127663b
• fix(release): parameterize current package gates #714 only changed release-gate parameterization scripts/fixtures and had no overlap with this PR's changed files.
• The PR remains one focused commit; GenerationControl implementation/API/docs/package changes are unchanged.

Final validation on the current head:

• PR Fast: success
• PR Package Smoke: success
• CodeQL: success
• Codec Padding Security Evidence: success
• PR Extended: success
• PR Extended covered Debug/Release builds, admission rollback regression, Integration Tests, NativeAOT transport/topology smoke, pack/package verification, NuGet package smoke, Oneway demo, load smoke, and all six desktop codec compatibility producer/consumer lanes.
• Browser compatibility lanes were skipped by the workflow as configured.

The PR is open, Ready, cleanly mergeable, based directly on the current dev, and still contains one focused commit.

[SunSi12138]

Independent review completed: no blocking findings.

Checked:

• #691 initial-scope acceptance: authoritative desired/actual inventory, separate stage/activate operations, revision-based watch invalidation, provider boundary, and explicit NativeAOT process-replacement outcomes.
• Packaging/reference boundaries: SharpLink.GenerationControl has a runtime dependency only on SharpLink.Abstractions; SharpLink.Generator is analyzer-only and Runtime/Sdk/Generator are excluded from the runtime package dependency graph.
• Regression surface: Protocol v2 and ordinary RPC data paths are unchanged; the Generator change only adds XML documentation to generated manifest members required by production CS1591 policy.
• Release/public-API integration: solution, package verification, release publishing, reviewed API snapshot, and package smoke include the ninth package.
• Final-head CI: PR Fast, PR Package Smoke, CodeQL, Codec Padding Security Evidence, and PR Extended all pass. Extended includes Integration, NativeAOT smoke, packaging, package consumption, demo/load smoke, and desktop codec compatibility.

No correctness, regression-risk, maintainability, or Issue-acceptance problem warrants blocking this PR.

[SunSi12138]

已按 Issue #691 的验收条件和工程化风险完成 Review。

未发现需要阻塞或明显值得修改的问题。重点核对结果：

• SharpLink.GenerationControl 保持在 Protocol v2 / 普通数据路径之外，运行时依赖仅为 SharpLink.Abstractions；Generator 仅作为 analyzer 引用。
• desired/actual + endpoint-local revision、stage/activate 分离、WatchAsync 仅作 invalidation、provider/materialization 边界，以及 NativeAOT 的 process-replacement 语义均覆盖 #691 的初始范围。
• 新包已接入 solution、项目引用边界、NuGet/package smoke、reviewed public API 与 release publish gate；未发现漏包或错误依赖。
• 当前 head 5df13e2c1c8dd720c0da2c232fb3dd719127663b 直接基于当前 dev fa69e6c886ac882eb16425933ca0f6c09d1b46fc。
• 当前 head 的 PR Fast、PR Package Smoke、PR Extended、CodeQL、Codec Padding Security Evidence 均已实际完成且为 success；Extended 的 browser lanes 按工作流配置为 skipped。

结论：无阻塞项，可以按仓库规则合并。

[SunSi12138]

Post-merge verification completed.

• PR feat: add optional generation control extension #706 is merged into dev.
• Merge commit: dfc123fb00d5dae162000068385180326f5c7e6d.
• Current dev points at that merge commit.
• Final PR-head CI remained green before merge: PR Fast, PR Package Smoke, CodeQL, Codec Padding Security Evidence, and PR Extended.
• No unresolved review threads or remaining PR changes are pending.
• Linked Issue Proposal: optional generation-control extension for cross-endpoint dynamic module synchronization #691 is closed as completed with the implementation/review/CI outcome recorded.

No additional code or CI repair is required for this PR.