fix(federation): resolve spec versions like JS getMinimumRequiredVersion

`SpecDefinitions` resolved the spec version to use for a federation
version with `Version::satisfies`, which requires matching majors. That
only worked while fed 1 and fed 2 were the only majors: for federation
v3.0 every spec whose minimum federation version is v2.x (link,
inaccessible, tag, cost, context, ...) resolved to nothing, which is
what the `Version::satisfies_federation` carveout papered over.

The JS `FeatureDefinitions.getMinimumRequiredVersion` instead returns
the latest version whose minimum federation version is `<=` the given
one, clamped to the spec's latest major. Port it as
`get_maximum_allowed_version`, which is now the only lookup:

- Drop `get_minimum_required_version` (oldest compatible version with
  a matching major); for every fed 2.x version it resolves to the same
  spec versions as the ported lookup.
- Rename `get_dyn_minimum_required_version` to
  `get_dyn_maximum_allowed_version`.
- Drop `Version::satisfies_federation`.

JS: https://github.com/apollographql/federation/blob/7c0a8ba4cf061cf0e2a6537803ed828c36234bed/internals-js/src/specs/coreSpec.ts#L660-L675

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: dariuszkuc

apollo-federation/src/connectors/spec/type_and_directive_specifications.rs

@@ -461,7 +461,7 @@ fn connect_directive_spec() -> DirectiveSpecification {
         None,
         // Some(DirectiveCompositionOptions {
         //     supergraph_specification: &|v| {
-        //         CONNECT_VERSIONS.get_dyn_minimum_required_version(v)
+        //         CONNECT_VERSIONS.get_dyn_maximum_allowed_version(v)
         //     },
         //     static_argument_transform: None,
         //     use_join_directive: true,

apollo-federation/src/link/authenticated_spec_definition.rs

@@ -47,7 +47,7 @@ impl AuthenticatedSpecDefinition {
             ],
             Some(DirectiveCompositionOptions {
                 supergraph_specification: &|v| {
-                    AUTHENTICATED_VERSIONS.get_dyn_minimum_required_version(v)
+                    AUTHENTICATED_VERSIONS.get_dyn_maximum_allowed_version(v)
                 },
                 static_argument_transform: None,
                 use_join_directive: false,

apollo-federation/src/link/context_spec_definition.rs

@@ -136,7 +136,7 @@ impl SpecDefinition for ContextSpecDefinition {
                 DirectiveLocation::Union,
             ],
             Some(DirectiveCompositionOptions {
-                supergraph_specification: &|v| CONTEXT_VERSIONS.get_dyn_minimum_required_version(v),
+                supergraph_specification: &|v| CONTEXT_VERSIONS.get_dyn_maximum_allowed_version(v),
                 static_argument_transform: Some(Rc::new(Self::static_argument_transform)),
                 use_join_directive: false,
             }),

apollo-federation/src/link/cost_spec_definition.rs

@@ -316,7 +316,7 @@ impl CostSpecDefinition {
                 DirectiveLocation::Scalar,
             ],
             Some(DirectiveCompositionOptions {
-                supergraph_specification: &|v| COST_VERSIONS.get_dyn_minimum_required_version(v),
+                supergraph_specification: &|v| COST_VERSIONS.get_dyn_maximum_allowed_version(v),
                 static_argument_transform: None,
                 use_join_directive: false,
             }),
@@ -363,7 +363,7 @@ impl CostSpecDefinition {
             false,
             &[DirectiveLocation::FieldDefinition],
             Some(DirectiveCompositionOptions {
-                supergraph_specification: &|v| COST_VERSIONS.get_dyn_minimum_required_version(v),
+                supergraph_specification: &|v| COST_VERSIONS.get_dyn_maximum_allowed_version(v),
                 static_argument_transform: None,
                 use_join_directive: false,
             }),

apollo-federation/src/link/federation_spec_definition.rs

@@ -956,7 +956,7 @@ impl FederationSpecDefinition {
             ],
             Some(DirectiveCompositionOptions {
                 supergraph_specification: &|v| {
-                    CACHE_TAG_VERSIONS.get_dyn_minimum_required_version(v)
+                    CACHE_TAG_VERSIONS.get_dyn_maximum_allowed_version(v)
                 },
                 static_argument_transform: None,
                 use_join_directive: true,
@@ -1004,7 +1004,7 @@ impl SpecDefinition for FederationSpecDefinition {
         specs.push(Box::new(self.shareable_directive_specification()));
 
         if let Some(inaccessible_spec) =
-            INACCESSIBLE_VERSIONS.get_dyn_minimum_required_version(self.version())
+            INACCESSIBLE_VERSIONS.get_dyn_maximum_allowed_version(self.version())
         {
             specs.extend(inaccessible_spec.directive_specs());
         }

apollo-federation/src/link/inaccessible_spec_definition.rs

@@ -128,7 +128,7 @@ impl InaccessibleSpecDefinition {
             locations,
             Some(DirectiveCompositionOptions {
                 supergraph_specification: &|v| {
-                    INACCESSIBLE_VERSIONS.get_dyn_minimum_required_version(v)
+                    INACCESSIBLE_VERSIONS.get_dyn_maximum_allowed_version(v)
                 },
                 static_argument_transform: None,
                 use_join_directive: false,

apollo-federation/src/link/policy_spec_definition.rs

@@ -68,7 +68,7 @@ impl PolicySpecDefinition {
                 DirectiveLocation::Enum,
             ],
             Some(DirectiveCompositionOptions {
-                supergraph_specification: &|v| POLICY_VERSIONS.get_dyn_minimum_required_version(v),
+                supergraph_specification: &|v| POLICY_VERSIONS.get_dyn_maximum_allowed_version(v),
                 static_argument_transform: None,
                 use_join_directive: false,
             }),

apollo-federation/src/link/requires_scopes_spec_definition.rs

@@ -71,7 +71,7 @@ impl RequiresScopesSpecDefinition {
             ],
             Some(DirectiveCompositionOptions {
                 supergraph_specification: &|v| {
-                    REQUIRES_SCOPES_VERSIONS.get_dyn_minimum_required_version(v)
+                    REQUIRES_SCOPES_VERSIONS.get_dyn_maximum_allowed_version(v)
                 },
                 static_argument_transform: None,
                 use_join_directive: false,

apollo-federation/src/link/spec.rs

@@ -120,19 +120,6 @@ impl Version {
 
         self.major == min.major && self.minor >= min.minor && self.minor <= max.minor
     }
-
-    /// Whether this federation version satisfies the provided minimum federation version.
-    ///
-    /// Unlike [`Version::satisfies`], federation versions are cumulative across majors from v2.0
-    /// onwards: federation v3.0 supports everything federation v2.x does. Federation v1 remains a
-    /// separate line, so a fed 1 requirement is only satisfied by a fed 1 version.
-    pub(crate) fn satisfies_federation(&self, required: &Version) -> bool {
-        if required.major < 2 {
-            self.satisfies(required)
-        } else {
-            self >= required
-        }
-    }
 }
 
 /// A `@link` specification url, which identifies a specific version of a specification.
@@ -254,29 +241,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn federation_versions_satisfy_across_majors() {
-        let fed_1_0 = Version { major: 1, minor: 0 };
-        let fed_2_0 = Version { major: 2, minor: 0 };
-        let fed_2_12 = Version {
-            major: 2,
-            minor: 12,
-        };
-        let fed_3_0 = Version { major: 3, minor: 0 };
-
-        assert!(fed_3_0.satisfies_federation(&fed_2_0));
-        assert!(fed_3_0.satisfies_federation(&fed_2_12));
-        assert!(fed_3_0.satisfies_federation(&fed_3_0));
-        assert!(fed_2_12.satisfies_federation(&fed_2_0));
-        assert!(!fed_2_12.satisfies_federation(&fed_3_0));
-        assert!(!fed_1_0.satisfies_federation(&fed_2_0));
-
-        // Fed 1 requirements are only met by fed 1 versions.
-        assert!(fed_1_0.satisfies_federation(&fed_1_0));
-        assert!(!fed_2_0.satisfies_federation(&fed_1_0));
-        assert!(!fed_3_0.satisfies_federation(&fed_1_0));
-    }
-
     #[test]
     fn valid_versions_can_be_parsed() {
         assert_eq!(

apollo-federation/src/link/spec_definition.rs

@@ -268,30 +268,96 @@ impl<T: SpecDefinition> SpecDefinitions<T> {
         self.definitions.iter()
     }
 
+    /// Returns the latest spec version usable with the given federation version, i.e. the latest
+    /// one whose minimum federation version is at most `federation_version`.
+    ///
+    /// Only versions with the same major as the latest spec version are returned: if the matching
+    /// version has an older major, the oldest version with the latest major is returned instead.
+    // PORT_NOTE: This corresponds to `FeatureDefinitions.getMinimumRequiredVersion` in JS.
     pub(crate) fn get_maximum_allowed_version(
         &'static self,
         federation_version: &Version,
     ) -> Option<&'static T> {
-        self.definitions
+        let spec = self
+            .definitions
             .values()
             .rev()
-            .find(|spec| federation_version.satisfies_federation(spec.minimum_federation_version()))
-    }
-
-    pub(crate) fn get_minimum_required_version(
-        &'static self,
-        federation_version: &Version,
-    ) -> Option<&'static T> {
-        self.definitions
-            .values()
-            .find(|spec| federation_version.satisfies_federation(spec.minimum_federation_version()))
+            .find(|spec| federation_version >= spec.minimum_federation_version())?;
+        let latest_major = self.latest().version().major;
+        if spec.version().major != latest_major {
+            return self
+                .definitions
+                .values()
+                .find(|spec| spec.version().major == latest_major);
+        }
+        Some(spec)
     }
 
-    pub(crate) fn get_dyn_minimum_required_version(
+    pub(crate) fn get_dyn_maximum_allowed_version(
         &'static self,
         federation_version: &Version,
     ) -> Option<&'static dyn SpecDefinition> {
-        self.get_minimum_required_version(federation_version)
+        self.get_maximum_allowed_version(federation_version)
             .map(|spec| spec as &dyn SpecDefinition)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::link::cost_spec_definition::COST_VERSIONS;
+    use crate::link::inaccessible_spec_definition::INACCESSIBLE_VERSIONS;
+    use crate::link::join_spec_definition::JOIN_VERSIONS;
+    use crate::link::link_spec_definition::LINK_VERSIONS;
+    use crate::link::tag_spec_definition::TAG_VERSIONS;
+
+    fn v(major: u32, minor: u32) -> Version {
+        Version { major, minor }
+    }
+
+    fn maximum_allowed<T: SpecDefinition>(
+        definitions: &'static SpecDefinitions<T>,
+        federation_version: Version,
+    ) -> Option<Version> {
+        definitions
+            .get_maximum_allowed_version(&federation_version)
+            .map(|spec| spec.version().clone())
+    }
+
+    #[test]
+    fn maximum_allowed_version_is_latest_compatible_version() {
+        assert_eq!(maximum_allowed(&JOIN_VERSIONS, v(2, 0)), Some(v(0, 3)));
+        assert_eq!(maximum_allowed(&JOIN_VERSIONS, v(2, 7)), Some(v(0, 4)));
+        assert_eq!(maximum_allowed(&JOIN_VERSIONS, v(2, 15)), Some(v(0, 5)));
+        assert_eq!(maximum_allowed(&JOIN_VERSIONS, v(3, 0)), Some(v(0, 6)));
+    }
+
+    #[test]
+    fn maximum_allowed_version_skips_fed_1_versions_for_fed_2() {
+        // Tag v0.1/v0.2 and inaccessible v0.1 only require federation v1.0, but a later version is
+        // compatible with fed 2 and takes precedence.
+        assert_eq!(maximum_allowed(&TAG_VERSIONS, v(2, 0)), Some(v(0, 3)));
+        assert_eq!(
+            maximum_allowed(&INACCESSIBLE_VERSIONS, v(2, 0)),
+            Some(v(0, 2))
+        );
+        assert_eq!(maximum_allowed(&LINK_VERSIONS, v(2, 0)), Some(v(1, 0)));
+    }
+
+    #[test]
+    fn maximum_allowed_version_accepts_fed_2_versions_for_fed_3() {
+        assert_eq!(maximum_allowed(&TAG_VERSIONS, v(3, 0)), Some(v(0, 3)));
+        assert_eq!(
+            maximum_allowed(&INACCESSIBLE_VERSIONS, v(3, 0)),
+            Some(v(0, 2))
+        );
+        assert_eq!(maximum_allowed(&LINK_VERSIONS, v(3, 0)), Some(v(1, 0)));
+        assert_eq!(maximum_allowed(&COST_VERSIONS, v(3, 0)), Some(v(0, 1)));
+    }
+
+    #[test]
+    fn maximum_allowed_version_is_none_below_the_minimum_federation_version() {
+        assert_eq!(maximum_allowed(&COST_VERSIONS, v(2, 8)), None);
+        assert_eq!(maximum_allowed(&LINK_VERSIONS, v(1, 0)), None);
+    }
+}