Raise Aspire.TypeSystem AssemblyVersion freeze to high sentinel 10001.0.0.0

The shipped 1.0.0.0 freeze fixed old-CLI + new-SDK skew but regressed the common
backward-compat direction (new CLI + stable-channel SDK), where the bundled
Aspire.TypeSystem (1.0.0.0) could not satisfy the codegen assemblies' strong-named
reference to the real released version (e.g. 13.4.3.0). The CLR only binds when the
loaded copy's version is >= the requested version, so a single frozen value must sit
ABOVE every shipped real version to satisfy the must-work direction. Freeze at
10001.0.0.0 (a '1.0' seeded high; major slot is the breaking-change bump axis).

- Aspire.TypeSystem.csproj: AssemblyVersion 1.0.0.0 -> 10001.0.0.0; drop
  DisablePackageBaselineValidation (10001 >= package baseline, so CP0003 passes);
  rewrite rationale comment.
- IntegrationLoadContext: explain the bundled high copy satisfies any lower/equal
  reference; residual old-CLI case is #18125's actionable 'update your CLI' path.
- AssemblyLoader.WarnIfSharedAssemblyMismatch: warn only when bundled < libs (the
  only failing order); bundled >= libs binds and logs at Debug.
- AtsSharedContractSurfaceTests / SharedContractSurface: reframe the freeze guard
  around constant-version binding (content compat, not version) and reflow comments.

Fixes the regression behind #18110 and #17910; complements the #18125 diagnostics,
which still surface the genuine new-member case (already-shipped old CLI + post-freeze
codegen) as an actionable error.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: sebastienros

src/Aspire.Hosting.RemoteHost/AssemblyLoader.cs

@@ -236,19 +236,22 @@ private static List<Assembly> LoadAssemblies(
     /// or "no language support found" error with no actionable diagnostic.
     /// </para>
     /// <para>
-    /// Since <c>Aspire.TypeSystem</c> freezes its strong-name <c>AssemblyVersion</c> at a constant
-    /// decoupled from the build (see <c>src/Aspire.TypeSystem/Aspire.TypeSystem.csproj</c>), the
-    /// bundled and probed copies share an <see cref="AssemblyName.Version"/> for every CLI/SDK
-    /// combination. The version-equality check below therefore only trips when that constant has
-    /// been deliberately bumped for a binary-incompatible contract change, which is exactly the
-    /// case where an older bundled copy cannot satisfy a newer reference and genuinely warrants a
-    /// warning.
+    /// <c>Aspire.TypeSystem</c> freezes its strong-name <c>AssemblyVersion</c> at a high
+    /// constant (10001.0.0.0) decoupled from the build (see
+    /// <c>src/Aspire.TypeSystem/Aspire.TypeSystem.csproj</c>). The CLR satisfies a strong-named
+    /// reference when the loaded (bundled) copy's version is <c>&gt;=</c> the requested version,
+    /// so what matters is the ORDER of the two versions, not mere inequality. The bundled
+    /// high-versioned copy satisfies the (lower, real-versioned) reference of any already-released
+    /// SDK codegen assembly, and matches any post-freeze copy exactly. The only failing
+    /// configuration is a bundled copy whose version is STRICTLY LOWER than the libs copy -- an
+    /// already-shipped old CLI (real, lower version) paired with post-freeze libs referencing the
+    /// constant -- so the warning below trips only on that case.
     /// </para>
     /// <para>
-    /// The same-version/differing-MVID case (for example, a daily SDK build paired with a released
-    /// CLI build) is expected and harmless: strong-name binding keys on version + public key token,
-    /// not MVID, so the bundled copy still satisfies the reference. It is logged at Debug only, to
-    /// correlate with any unrelated <see cref="ReflectionTypeLoadException"/>.
+    /// When the bundled version is greater than or equal to the libs version (the supported
+    /// "new CLI + older SDK" backward-compat direction, or a same-version/differing-MVID pairing
+    /// such as a daily SDK build with a released CLI), binding succeeds and it is logged at Debug
+    /// only, to correlate with any unrelated <see cref="ReflectionTypeLoadException"/>.
     /// </para>
     /// </remarks>
     private static void WarnIfSharedAssemblyMismatch(string? integrationLibsPath, ILogger logger)
@@ -288,34 +291,38 @@ private static void WarnIfSharedAssemblyMismatch(string? integrationLibsPath, IL
             var defaultName = defaultAsm.GetName();
             var defaultMvid = defaultAsm.ManifestModule.ModuleVersionId;
 
-            if (defaultName.Version != probedName.Version)
+            if (defaultName.Version < probedName.Version)
             {
-                // With Aspire.TypeSystem's AssemblyVersion frozen at a build-decoupled constant,
-                // the bundled and probed copies only differ in version when that constant was
-                // bumped for a binary-incompatible contract change. Keep this as a warning: an old
-                // bundle paired with libs built after such a bump is exactly the configuration that
-                // fails to bind and silently skips integrations.
+                // The bundled copy's strong-name version is strictly lower than the libs copy,
+                // so it cannot satisfy the strong-named reference that the libs-side integration
+                // assemblies carry to Aspire.TypeSystem. With the version frozen at a high
+                // constant, this only happens for an already-shipped OLD CLI (a real, lower
+                // version) paired with libs built after the freeze (referencing the constant) --
+                // the unsupportable "update your CLI" case. The reference fails to bind and
+                // integrations are silently skipped during type discovery, so surface it here.
                 logger.LogWarning(
-                    "Shared assembly '{AssemblyName}' version mismatch: bundled={BundledVersion}, libs={LibsVersion} ({LibsPath}). " +
-                    "Integration assemblies referencing this assembly from the libs directory will fail to bind their type " +
-                    "references through the default load context, which causes integrations to be silently skipped during type discovery. " +
-                    "This typically indicates the apphost server bundle and the restored integration packages were produced by " +
-                    "different build configurations.",
+                    "Shared assembly '{AssemblyName}' version too low: bundled={BundledVersion}, libs={LibsVersion} ({LibsPath}). " +
+                    "The bundled copy is older than the integration packages and cannot satisfy their strong-named reference, " +
+                    "so integration assemblies will fail to bind their type references through the default load context and be " +
+                    "silently skipped during type discovery. The apphost server (CLI) is older than the restored Aspire packages; " +
+                    "update the Aspire CLI to a version at least as new as the packages.",
                     sharedName,
                     defaultName.Version,
                     probedName.Version,
                     libsPath);
                 continue;
             }
 
-            // Same version, different MVID (compiled from different sources, e.g. a daily SDK
-            // paired with a released CLI). This is expected and harmless: strong-name binding keys
-            // on version + public key token, not MVID, so the bundled copy still satisfies the
-            // reference. We can't read the probed MVID without loading the assembly, which we
-            // deliberately don't do here. Logging the bundled MVID at Debug helps correlate with
-            // any unrelated ReflectionTypeLoadException.
-            logger.LogDebug("Shared assembly '{AssemblyName}' identity matches: Version={Version}, BundledMvid={Mvid}",
-                sharedName, defaultName.Version, defaultMvid);
+            // Bundled version >= libs version: the bundled copy satisfies the libs' strong-named
+            // reference, so binding succeeds. This covers the supported "new CLI + older SDK"
+            // backward-compat direction (bundled strictly higher) and the
+            // same-version/differing-MVID pairing (e.g. a daily SDK paired with a released CLI) --
+            // strong-name binding keys on version + public key token, not MVID. We can't read the
+            // probed MVID without loading the assembly, which we deliberately don't do here.
+            // Logging the bundled identity at Debug helps correlate with any unrelated
+            // ReflectionTypeLoadException.
+            logger.LogDebug("Shared assembly '{AssemblyName}' satisfies libs reference: bundled={BundledVersion}, libs={LibsVersion}, BundledMvid={Mvid}",
+                sharedName, defaultName.Version, probedName.Version, defaultMvid);
         }
     }
 

src/Aspire.Hosting.RemoteHost/IntegrationLoadContext.cs

@@ -50,17 +50,19 @@ internal IntegrationLoadContext(string[] probeDirectories, IntegrationPackagePro
             // AtsContext, etc.) work across the ALC boundary without requiring
             // reflection or marshalling.
             //
-            // This binds Aspire.TypeSystem to the copy bundled in the apphost server
-            // (the CLI's version), which can be OLDER than the SDK-restored codegen
-            // assemblies loaded below (the supported "old CLI + new SDK" case). That is
-            // only safe because Aspire.TypeSystem freezes its strong-name AssemblyVersion
-            // to a constant decoupled from the build (see
-            // src/Aspire.TypeSystem/Aspire.TypeSystem.csproj): as long as the shared contract
-            // is unchanged, the older bundled copy satisfies the newer codegen assembly's
-            // versioned reference regardless of CLI/SDK skew, so this short-circuit cannot
-            // reintroduce the ReflectionTypeLoadException that silently dropped generators
-            // (#18110, #17910). The version is bumped only on a binary-incompatible contract
-            // change, which is exactly the case an older copy genuinely cannot satisfy.
+            // This binds Aspire.TypeSystem to the copy bundled in the apphost server (the CLI's
+            // version). That is safe because Aspire.TypeSystem freezes its strong-name
+            // AssemblyVersion to a high constant (10001.0.0.0) decoupled from the build (see
+            // src/Aspire.TypeSystem/Aspire.TypeSystem.csproj). The CLR satisfies a strong-named
+            // reference when the loaded copy's version is >= the requested version, so the bundled
+            // high-versioned copy satisfies the (lower, real-versioned) reference of any already
+            // released SDK codegen assembly -- the supported "new CLI + older SDK" backward-compat
+            // case -- and exactly matches any post-freeze codegen assembly (also 10001.0.0.0). This
+            // avoids the ReflectionTypeLoadException that silently dropped generators (#18110,
+            // #17910). The only case this short-circuit cannot satisfy is an already-shipped
+            // OLD CLI (bundling a real, lower version) running post-freeze codegen that references
+            // the high constant; that is the unsupportable "update your CLI" case surfaced
+            // actionably by the #18125 diagnostics, not silently here.
             return null;
         }
 

src/Aspire.TypeSystem/Aspire.TypeSystem.csproj

@@ -17,43 +17,47 @@
       ILanguageSupport, AtsContext) keep a single type identity across the boundary
       (see src/Aspire.Hosting.RemoteHost/IntegrationLoadContext.cs and docs/specs/bundle.md).
 
-      The language codegen assemblies (Aspire.Hosting.CodeGeneration.*) are restored from the
-      SDK side and can be NEWER than the bundled CLI copy (the supported "old CLI + new SDK"
-      transition, bundle.md "Scenario 3"). These assemblies are strong-named (StrongNameKeyId=Open),
-      so a build-floating AssemblyVersion (e.g. 13.5.0.0) would make the older bundled copy unable
-      to satisfy a newer codegen assembly's strong-named reference. The reference fails to bind,
-      Assembly.GetTypes() throws ReflectionTypeLoadException, and every generator is silently
-      dropped -> "No code generator/language support found" (issues #18110, #17910).
-
-      The root problem is that AssemblyVersion moves on every build even when the contract is
-      byte-for-byte unchanged (the 13.4 -> 13.5 regression changed nothing in this assembly except
-      the strong-name version). So instead of tracking the product version, FREEZE AssemblyVersion
-      at a constant that is decoupled from the build: any CLI/SDK combination binds regardless of
-      minor/patch/MAJOR skew as long as the shared contract is unchanged.
-
-      Bump this constant ONLY when the shared contract changes in a binary-incompatible way (a member
-      is removed or its signature changes). Such a change is exactly when an older bundled copy can no
-      longer satisfy a newer reference, so a version bump is the correct signal for it; an additive
-      change (new members only) keeps the same version because an older copy still satisfies callers.
-      AtsSharedContractSurfaceTests is the back-compat guard: it fails on ANY surface change, forcing a
-      deliberate decision about whether the change is additive (no bump) or breaking (bump this value).
-
-      Only AssemblyVersion is frozen; FileVersion, InformationalVersion, and the NuGet package version
-      remain build-derived so diagnostics keep real build identities. Aspire.TypeSystem is consumed
-      only via ProjectReference (no PackageReference consumers), so the frozen AssemblyVersion is not a
-      package contract anyone binds to by exact version.
-
-      Freezing AssemblyVersion below the last-shipped value (13.4.0.0) intentionally violates package
-      baseline validation's CP0003 rule, which requires a monotonically non-decreasing AssemblyVersion
-      versus the PackageValidationBaselineVersion (src/Directory.Build.props). That rule exists to
-      protect strong-name package consumers, but this package has none (ProjectReference only) and its
-      strong-name version is now deliberately decoupled from the package version. So disable package
-      baseline validation here, matching the sibling Aspire.Hosting.CodeGeneration.* packages in the
-      same polyglot-codegen subsystem. The additive-vs-breaking contract is still enforced at the
-      source level by AtsSharedContractSurfaceTests, so this does not weaken back-compat protection.
+      The language codegen assemblies (Aspire.Hosting.CodeGeneration.*) are restored from the SDK
+      side and reference this assembly by strong name (StrongNameKeyId=Open). The CLR satisfies a
+      strong-named reference only when the loaded (here: bundled) copy's AssemblyVersion is GREATER
+      THAN OR EQUAL TO the requested version. If AssemblyVersion floated with the build, the version
+      on either side would diverge whenever the CLI and SDK were built at different times, the
+      reference would fail to bind, Assembly.GetTypes() would throw ReflectionTypeLoadException, and
+      every generator would be silently dropped -> "No code generator/language support found"
+      (issues #18110, #17910). A floating version cannot satisfy BOTH skew directions at once: it
+      necessarily breaks either "new CLI + older Aspire.Hosting" (backward compat, bundle.md
+      "Scenario 2") or "old CLI + newer Aspire.Hosting".
+
+      Fix: FREEZE AssemblyVersion at a high constant decoupled from the build. The value must sit
+      ABOVE every already-shipped real version so the bundled copy satisfies the (lower, real)
+      reference of any already-released codegen assembly -> the common, must-work backward-compat
+      direction (a current CLI running an existing app) binds. Going forward, every CLI and SDK
+      built after this freeze carries the same constant, so they match exactly and no skew matters.
+      10001.0.0.0 is chosen as a "1.0" seeded high enough to clear all real product versions for
+      the product's lifetime (AssemblyVersion components are capped at 65535); the major slot is
+      the bump axis (10001 -> 10002) for the rare breaking change below.
+
+      The only residual hard-bind failure is an already-shipped OLD CLI (bundling a real, lower
+      version) paired with post-freeze codegen referencing this constant. That is the genuinely
+      unsupportable "the CLI predates this build" case: it cannot be fixed for an immutable shipped
+      CLI regardless of the freeze value, and the user must update the CLI. The #18125 diagnostics
+      turn that into an actionable "run aspire update" message. (Post-freeze CLIs never hit it: they
+      all bundle this constant and satisfy any post-freeze reference.)
+
+      Bump this constant ONLY when the shared contract changes in a binary-incompatible way (a
+      member is removed or its signature changes); an additive change (new members only) keeps the
+      same value. AtsSharedContractSurfaceTests is the back-compat guard: it fails on ANY surface
+      change, forcing a deliberate decision about whether the change is additive (no bump) or
+      breaking (bump this value).
+
+      Only AssemblyVersion is frozen; FileVersion, InformationalVersion, and the NuGet package
+      version remain build-derived so diagnostics keep real build identities. Aspire.TypeSystem is
+      consumed only via ProjectReference (no PackageReference consumers), so the frozen
+      AssemblyVersion is not a package contract anyone binds to by exact version. Because
+      10001.0.0.0 is >= the package baseline version, package baseline validation (CP0003) still
+      passes, so no validation override is required.
     -->
-    <AssemblyVersion>1.0.0.0</AssemblyVersion>
-    <DisablePackageBaselineValidation>true</DisablePackageBaselineValidation>
+    <AssemblyVersion>10001.0.0.0</AssemblyVersion>
   </PropertyGroup>
 
 </Project>